Skip to main content

API

Our data management platform provides the ability for you securely access referral data for your campaigns. One of the popular options is integrating directly with your CRM via API.

An API is the most efficient way for Rokt to deliver referral data to you. This is because it works in real-time, meaning that as soon as a referral is generated for your campaign, Rokt can communicate the lead to you. There are a few technical pieces required to get this completed, which are outlined below.

Requirements#

To begin the API setup, Rokt requires a few pieces of information.

The following details should be sent to your account manager:

  1. Full API documentation on how to create subscribers in your system.
  2. Technical contact details to help troubleshoot setup queries.
  3. Endpoints for any relevant environments (production, testing, staging, etc.).
  4. Method (e.g., GET, POST, PUT)
  5. Authentication (if any)
  6. Request body encoding (e.g., JSON, XML, URL Encoded)
  7. Required API parameters (Learn about what attributes Rokt can share.)
  8. Expected API responses to help Rokt accurately categorize leads delivered successfully versus those that were rejected.

API documentation#

API documentation can encompass some or all of the points listed as requirements such as:

  • Endpoint
  • Method
  • Body

This should detail exactly how Rokt can deliver leads to your system.

The API documentation as well as a technical contact should be sufficient to start the API setup process.

For a good example of API documentation, check out the Mailchimp API documentation.

Technical contact details#

Provide the relevant contact (either yourself or someone else on your team) who's best suited to address any questions about the API setup process.

The technical contact should be able to help with:

  • Verifying that test leads have been recorded successfully in your system
  • Explaining why we're receiving a response status of 403

For example:

John Smith

Technical Support

john.smith@company.com

Endpoint#

This is the location that Rokt should send data to. If you have a staging or testing endpoint, this will help the Rokt team during the setup and testing process so that no test leads are delivered to your live CRM.

For example: https://us9.api.mailchimp.com/3.0/lists/abcdefghij/members

Method#

This is the HTTP request type that Rokt uses to send data to your list. The majority of the time, this is a POST request.

Rokt supports the following submit methods:

  • GET
  • POST
  • PUT

Authentication#

Provide any authentication details necessary for Rokt to send you data. This could come in many forms, such as:

  • User name and password combination
  • An API key
  • Client ID and secret

API parameters#

Provide a list of parameters for Rokt to send through in each API request. If possible, specify any:

  • Required attributes (attributes that must be sent in order for the request to succeed)
  • Optional attributes
  • Parameter names for each attribute (whether to use firstname, FirstName, or first-name, for example)

Common attributes include:

  • Email
  • First name
  • Last lame
  • Source
  • Country

For reference, Rokt can share any of these attributes.

Rokt supports the following body encoding:

  • JSON
  • URL encoded
  • Plain text
  • XML

Expected API responses#

By providing a list of possible API responses, Rokt can set up response handling logic to quickly identify leads that were delivered successfully, versus those that failed to deliver or were labelled as duplicates.

The response handling could be created based on the status code we receive or the response body, depending on how your API is set up.

Example status codes:

  • 201 (lead created successfully)
  • 400 (unauthorized)
  • 500 (server error)

Example response body values:

  • "successfully delivered"
  • {"status": "duplicate"}
  • {"success": false}
caution

Work with your Rokt account manager to complete the API setup process described below.

Setting up the API connection#

  1. Navigate to your account in One Platform.

  2. Click Connections in the bottom left menu.

    Referral Export via API

  3. Click Add connection.

    Referral Export via API

  4. Under Referrals, click API.

    Referral Export via API

  5. Give your connection a name.

    Referral Export via API

  6. Enter the endpoint for your connection.

    Referral Export via API

  7. Enter all the required information under Authorization, Headers, and Body.

    Referral Export via API

  8. Enter all your Response handling rules.

    Referral Export via API

Testing your API connection#

  1. Once your API connection is set up (endpoint, authorization, headers, body, and response handling), click Settings.

    Referral Export via API

  2. Edit the testing settings according to your test criteria.

    Referral Export via API

  3. Click Save.

  4. Click Test.

    Referral Export via API

  5. Check your test result.

  6. Repeat tests until you've achieved your desired outcome.

Linking campaigns to your API connection#

  1. Go to the Real-time Referral page.

  2. Expand the connection that you want to link a campaign to.

    Referral Export via API

  3. Click Show unlinked.

    Referral Export via API

  4. Find the campaign that you want to link to your connection and click Link.

    Referral Export via API

  5. The campaign is now linked to your connection.

    Referral Export via API

Unlinking campaigns from your API connection#

  1. Go to the Real-time Referral page.

  2. Expand the connection that you want to link a campaign to.

    Referral Export via API

  3. Find the campaign that you want to unlink from your connection and click Unlink.

    Referral Export via API

  4. Click Show unlinked.

    Referral Export via API

  5. Confirm that your campaign is now unlinked from your connection.

    Referral Export via API

Was this article helpful?