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 is available here: https://app.swaggerhub.com/apis-docs/Claravine/claravine-api

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. Click Settings in the Navigation menu.
   
   
2. Click your Name in the Sub-Navigation menu.

           The Profile Settings page displays.

3. In the API Keys section, click Create API Key.
   
   
4. The API Key and API Shared Secret display. The Created and Expiration 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.
   
   
   
5. Navigate to https://app.swaggerhub.com/apis-docs/Claravine/claravine-api, 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.
   
   
   
6. Click Authorize.
   
   
7. Enter your Claravine API Key and click Authorize.
   
   
   
8. Enter your Claravine Secret and click Authorize. Close the window.
   
   
9. Use the provided GET datasets to pull data from Claravine.
    Use the API to GET data submitted through the Claravine Platform or API.
   
   
10. 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.

USING THE API

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 uuid's 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. 

Add the following key and values Header values:

Key=start-date        Value=YYYY-MM-DD

Key=end-date         Value=YYYY-MM-DD

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.