Claravine API

Claravine offers a secure REST API that allows customers to implement their own custom solutions that interface with Claravine. The core facets of the API currently focus on submissions: create submissions, view submissions, and search for specific data across submissions. Details about all API endpoints are available here.

The API is a paid integration and must be enabled on your account by your CSM. Please reach out to your CSM and/or Account Executive for more details about using the API.

To create a secure API Key and API Secret to access the API:

1. Navigate to Settings and click your Name.
   The Profile Settings page displays.
   
   
   
   
2. In the API Keys section, click Create API Key.
   
   
3. The API Key and API Shared Secret display. The Created and Expires date populate.
   This is the only time the API Secret is ever visible. Due to the highly secure nature of this secret, it is impossible to recover this secret like you would a forgotten password. If the secret is lost, then you’ll need to delete the old key and secret and create a new key and secret.
   
   
   
   
4. Navigate to https://claravine.readme.io/reference/getting-started-with-your-api-2, the API platform for Claravine. Bookmark the API link without a specific version specified to to ensure you are always viewing the latest version of the API.
   
   
   
   
5. Click Authorize.
   
   
6. Enter your Claravine API Key and click Authorize.
   
   
   
   
7. Enter your Claravine Secret and click Authorize. Close the window.
   
   
8. Use the provided GET datasets to retrieve data from Claravine. Use the API to retrieve data submitted through the Claravine Platform or API.
   
   
9. Use the provided POST dataset to submit data to Claravine.

GET and POST actions are available to the authenticated user based on template permission in the Claravine platform. If the template dataset you need is not available to you, please confirm your user account permissions with your Administrator.

Endpoints

GET "Dataset" = Return the list of datasets/templates uuid's available to the user. The Group assignment determines which templates a user can retrieve data from via the API.

Example URL: https://[customer].claravine.com/v1/datasets

GET "Transaction" = Return the list of transaction/submissions UUIDs for the dataset/template entered. You can GET only one dataset at a time, not all data per day.

Example URL: https://[customer].claravine.com/v1/datasets/{dataset uuid}/transactions/

GET "Data"= Return the header and data on the transaction/submission.

Example URL: https://[customer].claravine.com/v1/datasets/{dataset uuid}/transaction/{transaction uuid}/data/

GET Dataset for a time period = Return transactions within a certain time period.

Supply the start and end dates in the query string like this: /transactions?start-date=2023-03-01&end-date=2023-04-10

POST "Data" = Import data to a specified template in Claravine. The field and template governance applies as if using the Claravine platform, any invalid data will fail the submission without notice to the submitter, use Confirm Status steps to ensure submission was completed.

Failed submissions can be done in the Claravine platform or uploaded as a new, separate POST.

Current configuration allows a maximum of 1,000 rows per POST request.

Example URL: https://[customer].claravine.com/v1/datasets/{dataset uuid}/data

Example POST:

{
    "transactionName": "Football Season API v2",
    "fields": [
        "Campaign Name",
        "Site ID",
        "Country",
        "Audience Target",
        "Brand vs Demand Gen",
        "Budget Owner",
        "Budget Team",
        "Launch Month",
        "Fiscal Year",
        "Objective",
        "Retail Season",
        "Season Code",
        "Marketed Product Name"
    ],
    "rows": [
        [
            "Football Season",
            "111111",
            "US",
            "Prospecting",
            "Brand",
            "Agency",
            "Mass Media",
            "September",
            "FY21",
            "Purchase",
            "Fall",
            "",
            "Jacket"
        ],
        [
           "Football Season",
            "222222",
            "Canada",
            "Retargeting",
            "Demand",
            "Agency",
            "Mass Media",
            "October",
            "FY21",
            "Purchase",
            "Fall",
            "",
            "Sweater"
        ]
    ]
}

Confirm Status = Show the status of the submission: Pending, Complete, Failed.

Example URL: https://[customer].claravine.com/v1/datasets/{dataset uuid}/transactions/{transaction uuid}/status/

The API is continuing to grow and expand all the time. Please reach out to your CSM for any questions about current or future API functionality.