Connect Sitecore CDP to an external API

This walkthrough describes how to connect Sitecore CDP to an external API. After creating this connection, you can add it to an audience export in order to send the output of the audience export to third-party systems.

This walkthrough describes how to:

Before you begin

Have permission to create connections in Sitecore CDP.
Make sure the external API endpoint returns a JSON object, contains the Content-Type: application/json response header, and that the response status code is 200 OK.

Connect Sitecore CDP to an external API

To create a connection to an external API:

On the navigation menu, click Developer center > Connections > Create > External API.
On the Name & Describe screen, complete the following fields:
- Name - enter a unique, intuitive name for the connection.
- Description - enter a concise description of the connection.
Click Next to proceed to the Authenticate page.

Authenticate the connection

After you name the connection, you must authenticate the connection to the external API. We recommend that you use OAuth 2, when possible.

To authenticate the connection:

On the Authenticate page, click one of the following authentication methods and complete the required fields:
- OAuth 2:
  - Access Token URL - enter the URL to the access token of the external API. The access token is generated by the external API. The access token must use an HTTPS URL. This ensures you are using a secure connection.
  - Authentication option - select the Header option to pass the authentication credentials in the header or select the Body option to pass the authentication credentials in the body of the request.
  - Client ID - enter the client ID of the external API.
  - Client Secret - enter the client secret of the external API.
  - Headers - optionally, click Show headers and enter the key in the first field and the value in the second field. To enter additional headers, click Add Headers. If you selected Header for the Authentication option, you must enter the authentication parameters and values here.
  - URL encoded form - optionally, click Show URL encoded form and enter the key in the first field and the value in the second field. To enter additional items, click Add form item. This option enables you to convert keys and values into a valid URL format that you can send to Sitecore CDP.
  - Configure with Mutual TLS - click to enable Mutual Transport Layer Security (mTLS). This lets Sitecore CDP and the external API that you're connecting to, authenticate each other using the TLS protocol.
    
    To view Sitecore CDP's mTLS JSON Web Key Set (JWKS) endpoint, click the icon. The JWKS is a set of keys containing the public keys used to verify any JSON Web Tokens (JWT).
- Basic:
  - Username - enter the username for authenticating credentials to the external API.
  - Password - enter the password for authenticating credentials to the external API.
- None - this is only used for public APIs and is not recommended for connecting to an external API.
Click Next to proceed to the Configure Request page.

Configure the request

When you configure the request, you can set the headers and parameters that represent the metadata associated with the REST API request and response. Headers and parameters contain information that can help you troubleshoot issues.

To configure the request:

On the Configure Request page, in the Request URL drop-down list, select one of the following HTTP methods to use in the request:
In the Request URL field, enter the URL to send the API request.

Important

Connections for audience exports do not support variables such as ${friendlyId} in the request URL.
Click Show Default Headers to display the default headers and parameters for the external API:
- Accept - this field displays application/json to specify that JSON is the accepted format for the response.
- Accept-Encoding - this field displays gzip to specify that gzip is the accepted compression type.
- Content-Type - this field displays application/json to specify that JSON is the format of the content sent in the request.
To add additional headers, click Add Header. An additional row displays to enter the following:
- Key - enter the header name.
- Value - enter the parameter.
Important

Connections for audience exports do not support variables such as ${friendlyId} in headers.
To configure the connection timeout, fill in the following fields:
- Connection Timeout (ms) - in the drop-down list, select the number of milliseconds of inactivity after which the connection will close. The default is 1000.
- Read Timeout (ms) - in the drop-down list, select the number of milliseconds between connectivity being established and not receiving a response from the server after which the connection will close. The default is 1000."
In the Request field, click Request attributes > Copy all, then paste the copied content into the Request field.

The copied content is a JSON object of audience export notification attributes. We recommend you use these attributes if you plan to use this connection for audience exports. Alternatively, you can enter a payload of your choice.

Important

Connections for audience exports do not support custom variables in the request payload. Only the variables in the standard attributes are supported.
Click Test Request > Run Test, then click Next.

The results of the test display in the Response field with the relevant status code.
On the Map screen, click Next.
On the Review & Save screen, you can see a consolidated view of your connection. Check that the connection is correct.

Danger

After you save, you cannot edit the connection. Review it before saving.
Click Next to proceed to the Review & Save page.

The connection is created, and you can now add it to an audience export.

Do you have some feedback for us?

If you have suggestions for improving this article,