--- schema_version: "1" id: 1ceba06dae79c4aaaa8b4b24953b4f3e32bb9b6c9690a6993d7e675be6ff0922 title: Briefs (REST API) collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/mc-core/references/generated-api-specs/mc-rest-briefs.md canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-rest-briefs source_site: developer.salesforce.com content_type: documentation content_hash: e899601c5805e5b183b23ea8b522e44970702eec155401a3fba3dbaf3ae51081 products: - Marketing Cloud Next - Marketing Cloud --- Briefs (REST API) # Briefs (REST API) Manage and modify Marketing Cloud Next briefs synchronously by using REST API. This table lists the brief-related use cases that REST API supports. | Supported Use Case | HTTP Verb | URI | | --- | --- | --- | | Create a brief | [POST](/docs/marketing/marketing-cloud-growth/references/mc-rest-briefs?meta=Create%2Ba%2BBrief) | /services/data/{apiVersion}/sobjects/brief | | Get a brief | [GET](/docs/marketing/marketing-cloud-growth/references/mc-rest-briefs?meta=Get%2Ba%2BBrief) | /services/data/{apiVersion}/sobjects/brief/{briefId} | | Delete a brief | [DELETE](/docs/marketing/marketing-cloud-growth/references/mc-rest-briefs?meta=Delete%2Ba%2BBrief) | /services/data/{apiVersion}/sobjects/brief/{briefId} | | Update a brief | [PATCH](/docs/marketing/marketing-cloud-growth/references/mc-rest-briefs?meta=Update%2Ba%2BBrief) | /services/data/{apiVersion}/sobjects/brief/{briefId} | | Get updated briefs | [GET](/docs/marketing/marketing-cloud-growth/references/mc-rest-briefs?meta=Get%2BUpdated%2BBriefs) | /services/data/{apiVersion}/sobjects/brief/updated/ | | Get deleted briefs | [GET](/docs/marketing/marketing-cloud-growth/references/mc-rest-briefs?meta=Get%2BDeleted%2BBriefs) | /services/data/{apiVersion}/sobjects/brief/deleted/ | **Version:** 68.0 ## Servers * `https://{subdomain}.my.salesforce.com` * `subdomain (default None) The unique API subdomain for your Salesforce org.` ## Operations ### POST Create a brief record. `POST /services/data/{apiVersion}/sobjects/brief` Operation ID: `Create a Brief`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to REST API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` #### Request body (required) Media type: `application/json`. Schema: `briefUpdateRequestBody`. #### Responses * **201** This response indicates that the API accepted your request to create a brief. Media type: `application/json`. Schema: `briefResponseBody`. _Example_ ``` { "id": "003SB000002UaPtYAK", "success": true, "errors": [] } ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that your authorization token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` ### GET Retrieve a brief record. `GET /services/data/{apiVersion}/sobjects/brief/{briefId}` Operation ID: `Get a Brief`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to REST API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `briefId` (query, string, required) The record ID of the brief. #### Responses * **200** This response indicates that the API accepted your request to retrieve information about a brief. Media type: `application/json`. Schema: `getBriefResponseBody`. * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that your authorization token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that your request included the correct record ID for the brief. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "errorCode": "NOT_FOUND", "message": "Provided external ID field does not exist or is not accessible: 003SB000002MCarYAGG" } ] ``` ### DELETE Delete a brief record. `DELETE /services/data/{apiVersion}/sobjects/brief/{briefId}` Operation ID: `Delete a Brief`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to REST API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `briefId` (query, string, required) The record ID of the brief. #### Responses * **204** Indicates that the API accepted your request to delete the brief. The response contains no content. * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that your authorization token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that your request included the correct record ID for the brief. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "errorCode": "NOT_FOUND", "message": "Provided external ID field does not exist or is not accessible: 003SB000002MCarYAGG" } ] ``` ### PATCH Update one or more fields in a brief record. `PATCH /services/data/{apiVersion}/sobjects/brief/{briefId}` Operation ID: `Update a Brief`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to REST API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `briefId` (query, string, required) The record ID of the brief. #### Request body (required) Media type: `application/json`. Schema: `briefUpdateRequestBody`. #### Responses * **204** Indicates that the API accepted your request to update the brief. The response contains no content. * **400** This response indicates that the API wasn’t able to process your request. This error can occur if you specify an incorrect field name or parameter. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "No such column 'AudienceTarget' on sobject of type Brief", "errorCode": "INVALID_FIELD" } ] ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that your authorization token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that your request included the correct record ID for the brief. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "errorCode": "NOT_FOUND", "message": "Provided external ID field does not exist or is not accessible: 003SB000002MCarYAGG" } ] ``` ### GET Get a list of briefs that were modified within a specified range of dates. `GET /services/data/{apiVersion}/sobjects/brief/updated/` Operation ID: `Get Updated Briefs`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to REST API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `start` (query, string (date-time), required) The start date for the query. Express the date as an ISO 8601 timestamp string, such as `2024-08-05T00:00:00.000Z`. * `end` (query, string (date-time), required) The end date for the query. Express the date as an ISO 8601 timestamp string, such as `2024-08-05T00:00:00.000Z`. #### Responses * **200** This response indicates that the API accepted your request to retrieve information about briefs that were modified or deleted in the specified date range. Media type: `application/json`. Schema: `getUpdatedBriefsResponseBody`. _Example_ ``` { "ids": [ "21yWs0000003ZfZIAU", "21yWs0000003bxVIAQ" ], "latestDateCovered": "2024-08-01T08:14:00.000+0000" } ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that your authorization token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` ### GET Get a list of briefs that were deleted within a specified range of dates. `GET /services/data/{apiVersion}/sobjects/brief/deleted/` Operation ID: `Get Deleted Briefs`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to REST API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `start` (query, string (date-time), required) The start date for the query. Express the date as an ISO 8601 timestamp string, such as `2024-08-05T00:00:00.000Z`. * `end` (query, string (date-time), required) The end date for the query. Express the date as an ISO 8601 timestamp string, such as `2024-08-05T00:00:00.000Z`. #### Responses * **200** This response indicates that the API accepted your request to retrieve information about briefs that were modified or deleted in the specified date range. Media type: `application/json`. Schema: `getUpdatedBriefsResponseBody`. _Example_ ``` { "ids": [ "21yWs0000003ZfZIAU", "21yWs0000003bxVIAQ" ], "latestDateCovered": "2024-08-01T08:14:00.000+0000" } ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that your authorization token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` ## Schemas ### briefUpdateRequestBody * `Description` (_string_) A string that provides additional information about the purpose or usage of the brief. * `KeyMessage` (_string_) The main idea or message that you want to deliver to your customers through the campaign that’s associated with the brief. * `Name` (_string_) The name of the brief. * `TargetAudience` (_string_) A description of the characteristics of the audience that you want to reach through the campaign that’s associated with this brief. _Example_ ``` { "Description": "This campaign seeks to re-engage high-value customers by showing them popular products that they are likely to enjoy.", "KeyMessage": "We think you're going to enjoy these products.", "Name": "ProductRecs_HighValueCustomers_NW_SW", "TargetAudience": "Customers in the northwest and southwest regions who have made a purchase over $100 in the past year." } ``` ### briefResponseBody * `id` (_string_) The Salesforce ID of the brief. * `success` (_boolean_) Indicates whether the operation succeeded. * `errors` (_array of string_) Each item: An error message, if an error occurred. If no errors occurred, the array is empty. ### httpErrorResponseBody Array of `object`. * `errorcode` (_string_) The error message. * `message` (_string_) A detailed error message. ### getBriefResponseBody * `attributes` (_object_) * `type` (_string_) The type of the Salesforce object. For brief, this value is always `Brief`. * `url` (_string_) The API URL endpoint for the brief object. * `CreatedById` (_string_) The ID of the user that created the brief record. * `CreatedDate` (_string (date-time)_) A timestamp that indicates when the brief was created. * `Description` (_string_) A string that provides additional information about the purpose or usage of the brief. * `Id` (_string_) The unique Salesforce record ID for the brief. * `IsDeleted` (_boolean_) Indicates whether the object has been deleted. * `KeyMessage` (_string_) The main idea or message that you want to deliver to your customers through the campaign that’s associated with the brief. * `LastModifiedById` (_string_) The ID of the user that last modified the brief record. * `LastModifiedDate` (_string (date-time)_) A timestamp that indicates when the brief was last modified. * `LastReferencedDate` (_string (date-time)_) The timestamp when the current user last accessed this record, a record related to this record, or a list view. * `LastViewedDate` (_string (date-time)_) The timestamp when the current user last viewed this record or list view. If this value is null, it typically indicates that the user only accessed the record or list view but didn't view it. * `Name` (_string_) The name of the brief. * `SystemModstamp` (_string (date-time)_) A timestamp that indicates when the brief was last modified. * `TargetAudience` (_string_) A description of the characteristics of the audience that you want to reach through the campaign that’s associated with this brief. _Example_ ``` { "attributes": { "type": "Brief", "url": "/services/data/{apiVersion}/sobjects/Brief/21yWs0000003ZfZIAU" }, "Id": "21yWs0000003ZfZIAU", "IsDeleted": false, "Name": "ProductRecs_HighValueCustomers_NW_SW", "CreatedDate": "2024-08-01T17:54:41.000+0000", "CreatedById": "005Ws000000nDtlIAE", "LastModifiedDate": "2024-08-01T17:54:41.000+0000", "LastModifiedById": "005Ws000000nDtlIAE", "SystemModstamp": "2024-08-01T17:54:41.000+0000", "LastViewedDate": "2024-08-01T17:54:41.000+0000", "LastReferencedDate": "2024-08-01T17:54:41.000+0000", "KeyMessage": "We think you're going to enjoy these products.", "Description": "This campaign seeks to re-engage high-value customers by showing them popular products that they are likely to enjoy.", "TargetAudience": "Customers in the northwest and southwest regions who have made a purchase over $100 in the past year." } ``` ### getUpdatedBriefsResponseBody * `ids` (_array of string_) Each item: One or more brief IDs that were modified between the start date and the end date. * `latestDateCovered` (_string (date-time)_) The end date for the query.