--- schema_version: "1" id: 83ebb0d626f00369b0a410abde248fe2a44154b8ee2b79f675d86f6076327e5a title: Media External Accounts Integration API collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/industries-integrations/media_cloud/references/generated-api-specs/external_accounts.md canonical_url: https://developer.salesforce.com/docs/industries/media-cloud/references/external_accounts source_site: developer.salesforce.com content_type: documentation content_hash: 076b9528559f447a8be5d81de4d660d82ae1f8fbb8c38fcaec6748a505c13b0d products: - Media Cloud AdTech Integration API - Industries Integrations --- Media External Accounts Integration API # Media External Accounts Integration API Use the Media Integrations APIs to integrate Media Cloud apps with external systems. **Version:** v1 Protocols: HTTPS. ## Operations ### POST syncNewAccountToExternalSystem `POST /account` Creates the Account entity. #### Request body Media type: `application/json`. Schema: `Create_Account`. The Account to create. _Example_ ``` { "requestId": "RQST00001", "requestedBy": "Bianca White", "requestI18NInfo": { "localeName": "United States", "localeCode": "en-us", "timezone": "Apia Standard Time (Pacific/Apia)", "currencyName": "United States Dollar", "currencyCode": "USD" }, "requestMode": "Minimal", "adServerInstanceId": "INS0491032", "adServerCode": "Wide-Orbit", "adServerApplicationName": "Wide-Orbit", "accounts": [ { "id": "", "tentativeMappingId": "8f651263-0478-49ea-8811-153xxxxxx784", "accountType": "advertiser", "accountName": "Acme Global Test2", "description": "This is Acme Global Account based in US", "adServerUserId": "c7890ffa-bd35-f3ef-38f8-4c649xxxxxxf", "accountNumber": "AC00xxx13", "numberOfEmployees": 25000, "industry": "Consumption-Beverage", "parentId": "c7890ffa-bd35-f3ef-38f8-4c649xxxxxxf", "rating": "hot", "website": "http://www.acmeexample.com", "phone": "0000000000", "billingAddress": { "line1": "312 Line 1", "line2": "Address Line 2", "line3": "Line 3", "city": "Austin", "state": "TX", "zipCode": "78767", "country": "USA" }, "shippingAddress": { "line1": "312 Line1", "line2": "Constitution Place", "line3": "Line 3", "city": "Austin", "state": "TX", "zipCode": "78767", "country": "USA" }, "accountCode": "00xxx000xxxxk30YAD", "status": "InActive", "relatedAccounts": [], "additionalFields": {}, "attributes": { "careOf": "careOfExample", "externalId": "", "statementEmailAddress": "xyz@example.com", "isPending": false } } ] } ``` #### Responses * **200** The Account entity was created. Media type: `application/json`. Schema: `Create_Account_Response`. _Example_ ``` { "requestId": "RQST00001", "requestedBy": "Bianca White", "adServerInstanceId": "INS0491032", "result": { "status": "success", "code": 200, "additionalStatus": {}, "shortMessage": "", "verboseMessage": "" }, "addtionalInfo": [], "minimalResults": [ { "AC00xxx13": "8f651263-0478-49ea-8811-15323b9c9784" } ], "detailResults": [] } ``` * **400** There was an issue with your request. Media type: `application/json`. Schema: `ErrorMessage`. _Example_ ``` { "requestId": "RQST00001", "requestedBy": "Bianca White", "adServerInstanceId": "INS0491001", "result": { "status": "error", "code": 400, "additionalStatus": { "c7890ffa-bd35-f3ef-38f8-4c649xxxxxxf": { "errorMessage": "", "Related Accounts": [ { "accountId": "00xxx000xxxxk30YEX", "errorMessage": "" }, {} ] } }, "adServerLogId": "54uy-213i-9489-3121", "shortMessage": "BAD_REQUEST", "verboseMessage": "Errors: /items/0 required key [startDate] not found." }, "addtionalInfo": [], "minimalResults": [], "detailResults": [], "additionalFields": [] } ``` * **401** Authorization failed. Media type: `application/json`. Schema: `ErrorMessage`. _Example_ ``` { "requestId": "RQST00001", "requestedBy": "Bianca White", "adServerInstanceId": "INS0491001", "result": { "status": "error", "code": 401, "adServerLogId": "54uy-213i-9489-3121", "shortMessage": "Unauthorised", "verboseMessage": "Credentials are incorrect." }, "addtionalInfo": [], "minimalResults": [], "detailResults": [], "additionalFields": [] } ``` * **403** Request forbidden. Media type: `application/json`. Schema: `ErrorMessage`. _Example_ ``` { "requestId": "RQST00001", "requestedBy": "Bianca White", "adServerInstanceId": "INS0491001", "result": { "status": "error", "code": 403, "adServerLogId": "54uy-213i-9489-3121", "shortMessage": "Forbidden", "verboseMessage": "Request forbidden." }, "addtionalInfo": [], "minimalResults": [], "detailResults": [], "additionalFields": [] } ``` * **404** Resource not found. Media type: `application/json`. Schema: `ErrorMessage`. _Example_ ``` { "requestId": "RQST00001", "requestedBy": "Bianca White", "adServerInstanceId": "INS0491001", "result": { "status": "error", "code": 404, "adServerLogId": "54uy-213i-9489-3121", "shortMessage": "NotFound", "verboseMessage": "Resource not found." }, "addtionalInfo": [], "minimalResults": [], "detailResults": [], "additionalFields": [] } ``` * **405** Method not allowed. Media type: `application/json`. Schema: `ErrorMessage`. _Example_ ``` { "requestId": "RQST00001", "requestedBy": "Bianca White", "adServerInstanceId": "INS0491001", "result": { "status": "error", "code": 405, "adServerLogId": "54uy-213i-9489-3121", "shortMessage": "Method Not Allowed", "verboseMessage": "Method not allowed for this resource." }, "addtionalInfo": [], "minimalResults": [], "detailResults": [], "additionalFields": [] } ``` * **422** Unprocessable entity. Media type: `application/json`. Schema: `ErrorMessage`. _Example_ ``` { "requestId": "RQST00001", "requestedBy": "Bianca White", "adServerInstanceId": "INS0491001", "result": { "status": "error", "code": 422, "adServerLogId": "54uy-213i-9489-3121", "shortMessage": "Unprocessable Content", "verboseMessage": "Requested content can't be processed." }, "addtionalInfo": [], "minimalResults": [], "detailResults": [], "additionalFields": [] } ``` * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `ErrorMessage`. _Example_ ``` { "requestId": "RQST00001", "requestedBy": "Bianca White", "adServerInstanceId": "INS0491001", "result": { "status": "error", "code": 500, "adServerLogId": "54uy-213i-9489-3121", "shortMessage": "Internal Server Error", "verboseMessage": "The server encountered an unexpected condition that prevented it from fulfilling the request." }, "addtionalInfo": [], "minimalResults": [], "detailResults": [], "additionalFields": [] } ``` ### PUT syncExistingAccountToExternalSystem `PUT /account` Updates the Account entity. #### Request body Media type: `application/json`. Schema: `Update_Account`. The Account to update. _Example_ ``` { "requestId": "RQST00001", "requestedBy": "Bianca White", "requestI18NInfo": { "localeName": "United States", "localeCode": "en-us", "timezone": "Apia Standard Time (Pacific/Apia)", "currencyName": "United States Dollar", "currencyCode": "USD" }, "requestMode": "Minimal", "adServerInstanceId": "INS0491032", "adServerCode": "Wide-Orbit", "adServerApplicationName": "Wide-Orbit", "accounts": [ { "id": "c7890ffa-bd35-f3ef-38f8-4c649xxxxxxf", "accountType": "Advertiser", "accountCode": "00xxx000xxxxk30YAD", "status": "InActive", "relatedAccounts": [], "tentativeMappingId": "", "additionalFields": {}, "attributes": {} } ] } ``` #### Responses * **200** The Account entity was updated. Media type: `application/json`. Schema: `Update_Account_Response`. _Example_ ``` { "requestId": "RQST00001", "requestedBy": "Bianca White", "adServerInstanceId": "INS0491032", "result": { "status": "success", "code": 200, "additionalStatus": {}, "adServerLogId": "", "shortMessage": "", "verboseMessage": "" }, "additionalInfo":[], "minimalResults": [], "detailResults": [ { "id": "c7890ffa-bd35-f3ef-38f8-4c649xxxxxxf", "accountType": "Advertiser", "accountName": "Acme Global", "description": "This is Acme Global Account based in US", "accountNumber": "AC00xxx13", "accountCode": "00xxx000xxxxk30YAD", "status": "InActive", "relatedAccounts": [], "tentativeMappingId": "", "additionalFields": {}, "attributes": {} } ] } ``` * **400** There was an issue with your request. Media type: `application/json`. Schema: `ErrorMessage`. _Example: same as POST /account 400 response._ * **401** Authorization failed. Media type: `application/json`. Schema: `ErrorMessage`. _Example: same as POST /account 401 response._ * **403** Request forbidden. Media type: `application/json`. Schema: `ErrorMessage`. _Example: same as POST /account 403 response._ * **404** Resource not found. Media type: `application/json`. Schema: `ErrorMessage`. _Example: same as POST /account 404 response._ * **405** Method not allowed. Media type: `application/json`. Schema: `ErrorMessage`. _Example: same as POST /account 405 response._ * **422** Unprocessable entity. Media type: `application/json`. Schema: `ErrorMessage`. _Example: same as POST /account 422 response._ * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `ErrorMessage`. _Example: same as POST /account 500 response._ ## Schemas ### Create\_Account * `requestId` (_string_, required) The unique ID of the request. Example: `RQST00001`. * `requestedBy` (_string_, required) The account or the user who initiated the request. Example: `Bianca White`. * `requestI18NInfo` (_object_) The details about the locale, time zone, and currency configuration to be used by the request. Includes all fields of `I18NInfo`. * `requestMode` (_string_, required) Specifies if the response to receive is minimal or detailed. Valid values are Minimal and Detail. Allowed values: `Minimal`, `Detail`. Example: `Minimal`. * `adServerInstanceId` (_string_, required) The ID of the ad server instance. Example: `INS0491001`. * `adServerCode` (_string_, required) The code of the ad server to send the request to. Example: `WO`. * `adServerApplicationName` (_string_, required) The name of the ad server application to send the request to. Example: `Wide-Orbit`. * `accounts` (_array of Account_, required) The list of accounts to create. * `additionalFields` (_object_) Additional optional fields to include. Includes all fields of `KeyValuePair`. * `attributes` (_object_) Additional request attributes used by wide-orbit, boostr, and so on, and flows. Includes all fields of `KeyValuePair`. ### Create\_Account\_Response * `requestId` (_string_, required) The unique request ID. Example: `RQST00001`. * `requestedBy` (_string_, required) The account or user who initiated the request. Example: `Bianca White`. * `adServerInstanceId` (_string_, required) The ID of the ad server instance. Example: `INS0491001`. * `result` (_object_, required) A standard result. Includes all fields of `Result`. _Example_ ``` { "status": "success", "code": 200 } ``` * `additionalInfo` (_array of AdditionalInfo_) Additional Related Info. * `minimalResults` (_array of object_) The minimal response. _Example_ ``` - "00xxx000xxxxk30YAD": "c7890ffa-bd35-f3ef-38f8-4c649xxxxxxf" ``` Includes all fields of `KeyValuePair`. * `detailResults` (_array of object_) The detailed response. Includes all fields of `Account`. * `additionalFields` (_object_) Additional data to send. Includes all fields of `KeyValuePair`. ### ErrorMessage Shown when an API throws an error, typically with an HTTP error response code (3xx, 4xx, or 5xx). * `requestId` (_string_, required) The unique identifier of the request. Example: `RQST00001`. * `requestedBy` (_string_, required) The account or user who initiated the request. Example: `Bianca White`. * `adServerInstanceId` (_string_, required) The identifier of the ad server instance. Example: `INS0491001`. * `result` (_object_, required) The metadata of the error payload. Includes all fields of `Result`. * `additionalInfo` (_array of AdditionalInfo_) Additional Related Info. * `minimalResults` (_array of KeyValuePair_) The minimal response. * `detailResults` (_array of Account_) The detailed response. _Example_ ``` [] ``` * `additionalFields` (_array of any_) Additional data to send. _Example_ ``` [] ``` ### Update\_Account * `requestId` (_string_, required) The unique request ID. Example: `RQST00001`. * `requestedBy` (_string_, required) The account or user who initiated the request. Example: `Bianca White`. * `requestI18NInfo` (_object_) The details about the locale, time zone, and currency configuration to be used by the request. Includes all fields of `I18NInfo`. * `requestMode` (_string_, required) Specifies if the response to receive is minimal or detailed. Valid values are Minimal and Detail. Allowed values: `Minimal`, `Detail`. Example: `Minimal`. * `adServerInstanceId` (_string_, required) The ID of the ad server instance. Example: `INS0491001`. * `adServerCode` (_string_, required) The code of the ad server to send the request to. Example: `WO`. * `adServerApplicationName` (_string_, required) The name of the ad server application to send the request to. Example: `Wide-Orbit`. * `accounts` (_array of Account_, required) The list of accounts to update. * `additionalFields` (_object_) Additional optional fields to include. Includes all fields of `KeyValuePair`. * `attributes` (_object_) Additional request attributes used by wide-orbit, boostr, and so on, and flows. Includes all fields of `KeyValuePair`. ### Update\_Account\_Response * `requestId` (_string_, required) A unique request ID. Example: `RQST00001`. * `requestedBy` (_string_, required) The account or user who initiated the request. Example: `Bianca White`. * `adServerInstanceId` (_string_, required) The ID of the ad server instance. Example: `INS0491001`. * `result` (_object_, required) A standard result. Includes all fields of `Result`. _Example_ ``` { "status": "success", "code": 200 } ``` * `additionalInfo` (_array of AdditionalInfo_) Additional Related Info. * `minimalResults` (_array of object_) The minimal response. _Example_ ``` - "00xxx000xxxxk30YAD": "c7890ffa-bd35-f3ef-38f8-4c649xxxxxxf" ``` Includes all fields of `KeyValuePair`. * `detailResults` (_array of object_) The detailed response. Includes all fields of `Account`. * `additionalFields` (_object_) Additional data to send. Includes all fields of `KeyValuePair`. ### I18NInfo The I18N information of the request. * `localeCode` (_string_) The locale code of the request. Example: `en-us`. * `localeName` (_string_) The locale name of a request. Example: `United States`. * `currencyCode` (_string_) The currency code used in a request payload. Example: `USD`. * `currencyName` (_string_) The currency name related to the currencyCode property used in the request. Example: `United States Dollar`. * `timezone` (_string_) The time zone of the request. Example: `Apia Standard Time (Pacific/Apia)`. ### Account Details of an account. * `id` (_string_) The unique identifier for the account. Example: `c7890ffa-bd35-f3ef-38f8-4c649xxxxxxf`. * `accountType` (_string_) The type of the account, for example Advertiser, Agency, Brand, and so on. Example: `Advertiser`. * `accountName` (_string_) Name of the account. Example: `Acme Global`. * `description` (_string_) Description of the account. Example: `This is Acme Global Account based in US`. * `adServerUserId` (_string_) The userId to map to this account. Example: `c7890ffa-bd35-f3ef-38f8-4c649xxxxxxf`. * `accountNumber` (_string_) The accountNumber associated with the account. Example: `AC0012313`. * `numberOfEmployees` (_number_) The number of employees associated for this account. Example: `25000`. * `industry` (_string_) The industry this account is associated with. Example: `Consumption-Beverage`. * `parentId` (_string_) The parent account ID. Example: `c7890ffa-bd35-f3ef-38f8-4c649xxxxxxf`. * `rating` (_string_) The rating for this account. Example: `hot`. * `website` (_string_) The website for this account. Example: `http://www.acmeexample.com`. * `phone` (_string_) The phone number associated with this account. Example: `000000000`. * `address` (_object_) The address registered for this account with details such as street, city, state, and phone number. Includes all fields of `Address`. * `billingAddress` (_object_) The billing address registered for this account with details such as street, city, state, and phone number. Includes all fields of `Address`. * `shippingAddress` (_object_) The shipping address registered for this account with details such as street, city, state, and phone number. Includes all fields of `Address`. * `accountCode` (_string_, required) The account code to map with the external system ID. Example: `00xxx000xxxxk30YAD`. * `status` (_string_) The account status. Allowed values: `Active`, `InActive`. * `relatedAccounts` (_array of RelatedAccount_) Accounts that are associated with this account, such as agencies, brands, or an advertiser. * `relatedContacts` (_array of RelatedContact_) Contacts that are associated with this account. * `tentativeMappingId` (_string_) Tentative mapping ID for external systems. Applicable only for POST requests. Example: `c7890ffa-bd35-f3ef-38f8-4c649xxxxxxf`. * `additionalFields` (_object_) Additional optional fields the client wants to include. Includes all fields of `KeyValuePair`. * `attributes` (_object_) Additional request attributes used by wide-orbit, boostr, and flows. Includes all fields of `KeyValuePair`. ### KeyValuePair A key-value pair map. * `additionField1` (_any_) The additionField1 property value. _Example_ ``` additionField_1_Value ``` ### Result The metadata of the response payload. * `status` (_string_) Allowed values: `success`, `error`. * `code` (_integer_) A set of predefined codes similar to the HTTP status codes that indicate a business rule violation. * `additionalStatus` (_object_) The additional status for individual transactions. Includes all fields of `KeyValuePair`. * `adServerLogId` (_string_) The unique log ID of the request for troubleshooting. * `shortMessage` (_string_) If the request mode is minimal, send at least the minimum information required to understand the error case. * `verboseMessage` (_string_) If the request mode is detailed, send verbose information needed to understand the error case. ### AdditionalInfo The additional info in response payload. * `type` (_string_, required) The info type. Allowed values: `info`, `error`. Example: `info`. * `accountId` (_string_, required) The unique identifier for the account. * `relatedAccounts` (_object_) The info for relatedAccounts. Includes all fields of `KeyValuePair`. * `relatedContacts` (_object_) The info for relatedContacts. Includes all fields of `KeyValuePair`. ### Address Address details. * `id` (_string_) The unique identifier for the address. Example: `c7890ffa-bd35-f3ef-38f8-4c649xxxxxxf`. * `addressLine1` (_string_) Line 1 of the address. Example: `Address line 1`. * `addressLine2` (_string_) Line 2 of the address. Example: `Address line 2`. * `addressLine3` (_string_) Line 3 of the address Example: `Address line 3`. * `city` (_string_) The city in the address. Example: `Austin`. * `state` (_string_) The state in the address. Example: `Texas`. * `zipcode` (_string_) The zipcode for the address. Example: `77001`. * `country` (_string_) The country for the address. Example: `United States`. ### RelatedAccount Related Account details. * `id` (_string_, required) The unique identifier for the account-account relation. Example: `c7890ffa-bd35-f3ef-38f8-4c649xxxxxxf`. * `accountType` (_string_) The type of the account, for example Advertiser, Agency, Brand, and so on. Example: `Agency`. * `accountName` (_string_) Name of the account. Example: `Acme Global`. * `description` (_string_) Description of the account. Example: `This is Acme Global Account based in US`. * `address` (_object_) The address registered for this account with details such as street, city, state, and phone number. Includes all fields of `Address`. * `billingAddress` (_object_) The billing address registered for this account with details such as street, city, state, and phone number. Includes all fields of `Address`. * `shippingAddress` (_object_) The shipping address registered for this account with details such as street, city, state, and phone number. Includes all fields of `Address`. * `accountCode` (_string_, required) The account code to map with the external system ID. Example: `00xxx000xxxxk30YAD`. * `status` (_string_) The account status. Allowed values: `Active`, `InActive`. * `tentativeMappingId` (_string_) Tentative mapping ID for external systems. Applicable only for POST requests. Example: `c7890ffa-bd35-f3ef-38f8-4c649xxxxxxf`. * `additionalFields` (_object_) Additional optional fields the client wants to include. Includes all fields of `KeyValuePair`. * `attributes` (_object_) Additional request attributes used by wide-orbit, boostr, and flows. Includes all fields of `KeyValuePair`. ### RelatedContact Details of a Contact. * `id` (_string_, required) The unique identifier for the account-contact relation. Example: `c7890ffa-bd35-f3ef-38f8-4c649xxxxxxf`. * `contactType` (_string_) The type of contact, for example advertiser\_contact, billing\_contact, ad buyer and so on. Example: `AdBuyer`. * `title` (_string_) The title for the contact. Example: `Media Buyer`. * `saluation` (_string_) The salutation for the contact. Example: `Mr.`. * `firstName` (_string_) The first name of the contact. Example: `Sean`. * `lastName` (_string_) The last name of the contact. Example: `Sean`. * `description` (_string_) The description name of the contact. Example: `Mr Sean in Media Buyer`. * `email` (_string_) The email associated with this contact. Example: `sean@example.com`. * `department` (_string_) The department for this contact. Example: `Advertising`. * `phone` (_string_) The phone number associated with this contact. Example: `000000000`. * `address` (_object_) The address registered for this contact with details such as street, city, state, and phone number. Includes all fields of `Address`. * `mailingAddress` (_object_) The mailing address registered for this contact with details such as street, city, state, and phone number. Includes all fields of `Address`. * `contactCode` (_string_, required) The contact code to map with the external system Id. Example: `00xxx000xxxxk30YAD`. * `tentativeMappingId` (_string_) Tentative mapping Id for external systems. Applicable only for POST requests. Example: `c7890ffa-bd35-f3ef-38f8-4c649xxxxxxf`. * `additionalFields` (_object_) Additional optional fields the client wants to include. Includes all fields of `KeyValuePair`. * `attributes` (_object_) Additional request attributes used by wide-orbit, boostr, and flows. Includes all fields of `KeyValuePair`.