NAV

Introduction

Welcome to the Evocalize management API.

Request And Response

API Endpoint

https://partner-api-production.evocalize.com/

Requests

Evocalize has a majority of endpoints where the request and response is JSON formatted. At the same time, there are Multipart-Form endpoints for uploading content for an entity. Specify Content-Type accordingly.

Header Required Description
Content-Type true For JSON endpoints, application/json. For Multipart-Form endpoints, multipart/form-data.

For security and identity purposes, we require partners to provide authentication headers on all API requests. The required authentication request headers depend on your request's authentication type. Evocalize supports the following authentication types:

  1. Shared Secret
  2. Signature

If both authentication types are present in the request, Shared Secret takes precedence.

Shared Secret Authentication

Request Headers Example (Shared Secret)

X-Evocalize-Client-Key: 690a0ac5a5a219bb4a773f5bc116a325
X-Evocalize-Client-Key-Id: a5646c38-fc29-11e9-8f0b-362b9e155667

Pass in the client key and ID of the client key in your request. Evocalize should provide you with this information.

Header Required Description
X-Evocalize-Client-Key true Client Key provided by Evocalize.
X-Evocalize-Client-Key-Id true ID of the Client Key provided by Evocalize.

Signature Authentication:

Request Headers Example (Signature)

X-Evocalize-Client-Key-Id: a5646c38-fc29-11e9-8f0b-362b9e155667
X-Evocalize-Timestamp: 1667231735360
X-Evocalize-Signature: ba60ba1619762b3a06c88c4ed4e700c8a02aa1bf4a2eead8b41f8015c7902034

Request Signing Example

// Concatenate all the parts
val signatureParts = StringBuilder()
  .append(request.servletPath)
  .append("\n")
  // Omit this block if the request does not have a body
  .append(request.body())
  .append("\n")
  .append(request.headers["X-Evocalize-Timestamp"])
  .append("\n")
  // append the client key secret
  .append(myClientKeySecret)
  .toString()

// Take this value and pass it as the value for the header key "X-Evocalize-Signature"
val signature = Hashing.sha256().hashString(signatureParts, Charsets.UTF_8)

Join the following values with a new line character between each item

Header Required Description
X-Evocalize-Client-Key-Id true ID of the Client Key provided by Evocalize.
X-Evocalize-Timestamp true Unix time since epoch in seconds, e.g. October 30, 2020 @ 9:44pm (UTC) => 1604094273. Requests with a timestamp over a minute old will not be accepted.
X-Evocalize-Signature true Signature of the payload. See Signing Requests below.

Responses

JSON Response Schema

{
  "data": {
    // Request Specifc JSON object
  },
  "errors": [
    {
      "message": "String",
      "code": "String",
      "field": "String", // Omitted if null
      "details": {       // Omitted if null
        // JSON object
      }
    }
  ],
  "nextPageToken": "String",
  "previousPageToken": "String",
  "metadata": {
    // JSON object
  }
}

Success Response Example:

{
  "data": {
    // Request Specifc JSON Response
  }
}

Error Response Example:

{
  "errors": [
    {
      "message": "Unauthorized Request",
      "code": "EV_UNAUTHORIZED_MISSING_HEADERS"
    }
  ]
}

All requests are returned as JSON wrapped in a standard response format. The Schema section shows all the potential fields that we could return. Do note that we do not include null values. The most common responses will look like the examples provided.

Schema Field Always Present Description
data false Returned for requests that result with 2xx responses.
errors false Returned for requests that result in non 2xx responses.
nextPageToken false Page token appears for result sets larger than 100 items. Not present on last page of results.
previousPageToken false Same logic as nextPageToken. Not present on first page of results.
metadata false JSON object containing extra data around requests and responses. This data is subject to change and should not be relied on.

JWT Access Tokens

JWT Basics

The primary technology/concept used for authentication between our two systems is a JSON Web Token. The following link has documentation that you may find useful.

To create a valid JWT you will need to sign it with your evocalize jwt_secret using HS256 (HMAC with SHA-256). We will provide the jwt_secret value to you.

Variables you provide to Evocalize

Login URLs

You will need to provide us with Login URLs to send a user to if they arrive at the site unauthenticated or their login expires. Typically, we recommend having both a staging and a production endpoint when integrating.

SSO Endpoints for Evocalize Web App

This is where you will redirect your users after generating a JWT for them on your SSO page. See below for information you need to pass to this endpoint.

Authentication Flow

JWT Auth flow pseudo code example


// 0. Authenticate the user in your system to verify they are who they say they are.
user.authenticate();

// 1. Generate a JWT with the "sub" set to include the userId (same ID passed to Evocalize in API calls or feed files)
// note: `jwt_secret` will be provided by Evocalize
// here is an example JWT payload that we need you to generate:
const userJwtBlob = {
    sub: 'yourOrgSlug|' + user.id, // where yourOrgSlug is the value we provide you with and user.id with the ID you send in API calls or feed files.
    iat: 1563831852, // "Issued At" (seconds since Unix Epoch)
    exp: 1563835452 // "Expires At" (seconds since Unix Epoch) set to 1 hour after iat
};

const jwt = generateJwt(userJwtBlob, jwtSecret);

const path = encodeURIComponent("/#/dashboard/gallery") // any URL-encoded path will do

// 2. Redirect the user to a new Evocalize SSO endpoint with the JWT
redirectUser('https://your-white-label-domain.com/#/sso?token=' + jwt + '&path=' + path);

You will need to create a new SSO endpoint (or update your current one) to generate a token for your users using a secret key provided by Evocalize. You can then send your users to a specific endpoint to get them seamlessly authenticated in our application. The following workflow shows an example end-to-end process. Some of it is in pseudo code to keep things succinct. If any portions require clarity, please reach out to us, and we can assist you further.

Flow

User Management API

Get User

Get User Response

{
  "data": {
    "id": "test_user_id",
    "name": "Test User",
    "email": "example@evocalize.com",
    "groups": [
      {
        "id": "seattle_office",
        "name": "Seattle Office",
        "role": "group_admin"
      }
      // ...
    ]
  }
}

Returns a single user and associated groups.

HTTP Request

GET management/v1/user/{userId}

URL Params

URL Param type Required Description
userId String true The ID of the user you are wanting to retrieve

Response Codes:

Get Users

Get Users Response

{
  "data": [
    {
      "id": "1234",
      "name": "Test User 1",
      "email": "test1@evocalize.com"
    },
    {
      "id": "5678",
      "name": "Test User 2",
      "email": "test2@evocalize.com"
    },
    {
      "id": "91011",
      "name": "Test User 2",
      "email": "test3@evocalize.com"
    },
    {
      "id": "1213",
      "name": "Test User 3",
      "email": "test3@evocalize.com"
    }
  ],
  "nextPageToken": "test_next_page_token", // only present when there is another page
  "previousPageToken": "test_previous_page_token" // only present when there is a previous page
}

Returns all users. This is a paginated response - returning 100 results per page with optional page tokens to go to the next page and previous page if they exist.

HTTP Request

GET management/v1/users

Request Params

Param Required Description
pageToken false The page token (taken from either nextPageToken, or previousPageToken provided in the response) for the page you of results you want to view.

Response Codes:

Create Or Update User

Create Request Example

{
  "id": "1234",
  "email": "test1@evocalize.com",
  "name": "Test User 1",
  "groups": [
    {
      "groupId": "seattle_office",
      "role": "group_admin"
    }
    // ...
  ]
}

Update Request Example

{
  "id": "1234",
  "email": "test1@evocalize.com",
  "name": "Test User 1",
  "replaceGroups": false,
  "groups": [
    {
      "groupId": "seattle_office",
      "role": "group_admin"
    }
  ]
  // ...
}

Create and Update Response

{
  "id": "1234",
  "email": "test1@evocalize.com",
  "name": "Test User 1",
  "groups": [
    {
      "id": "seattle_office",
      "name": "Seattle Office",
      "role": "group_admin"
    }
    // ...
  ]
}

This endpoint allows you to create or update a user and their group associations. You are able to call this endpoint and omit the groups property. In the Create case, the user would be created, but not be associated to any groups. In the case of update we would only update their name and/or email.

The group you want to associate with the user MUST exist prior to making this call.

HTTP Request

POST management/v1/user

Create User Request Properties

Field Required Type Description
id true String ID of the user you are creating. This needs to be unique and immutable.
email true String Email of the user you are creating.
name true String Full name of the user you are creating.
groups false JSON Array Array of UserGroupAssociation objects. If this is not present on create or update, no groups will be added.

Update User Request Properties

Field Required Type Description
id true String ID of the user you are updating.
email false String Email of the user you are creating.
name false String Full name of the user you are creating.
replaceGroups false boolean When replaceGroups is true, we will REMOVE all groups currently associated to the user, replacing them with the groups provided in the list. By default this is false.
groups false JSON Array JSON Array of UserGroupAssociation objects. If this is not present on create or update the users group associations will remain unmodified.

User Group Association Properties

Field Required Type Description
groupId true String The Id of the group you want the user associated to.
role true String The role of the user within the group.

Valid group roles:

Response Codes:

Get User Associated Facebook Pages

Get User Associated Facebook Pages Response

{
  "data": [
    {
      "id": "12309817412312",
      "facebookPageName": "Big Time Facebook Page",
      "facebookPageId": "1231412312",
      "instagramId": "1231243154123"
    }
  ]
}

Returns a list of Facebook pages associated to the user.

HTTP Request

GET management/v1/user/{userId}/facebook/pages

URL Params

URL Param type Required Description
userId String true The ID of the user whose pages you want to view

Request Params

Param Required Description
pageToken false The page token (taken from nextPageToken provided in the response) for the page you want to retrieve.

Response Codes:

Get User Associated Media

Get User Associated Media Response

{
  "data": [
    {
      "id": "1234567890abcdef1234",
      "name": "My Image",
      "type": "image",
      "url": "https://www.example.com/1234567890abcdef1234.jpg"
    }
  ],
  "nextPageToken": "SnVzdCBhbiBleGFtcGxlIHRva2VuCg=="
}

Returns a list of media associated to the user.

HTTP Request

GET management/v1/user/{userId}/media

URL Params

URL Param type Required Description
userId String true The ID of the user whose media you want to view

Request Params

Param Required Description
type false The media type associated with the URL. Valid types are image, video.
pageToken false The page token (taken from nextPageToken provided in the response) for the page you want to retrieve.

Response Codes:

Create Or Update User Batch

Batch Create Request

[
  {
    "id": "1234",
    "email": "test1@evocalize.com",
    "name": "Test User 1",
    "groups": [
      {
        "groupId": "seattle_office",
        "role": "group_admin"
      }
      // ...
    ]
  }
  // ...
]

Batch Update Request

[
  {
    "id": "1234",
    "email": "test1@evocalize.com",
    "name": "Test User 1",
    "replaceGroups": false,
    "groups": [
      {
        "groupId": "8675309",
        "role": "group_admin"
      }
      // ...
    ]
  }
  // ...
]

Create and Update Batch Response

{
  "data": {
    "reportId": "HG3SrEndQch8dAZbjwBV"
  }
}

This endpoint allows you to pass a JSON Array of User Request objects for creation or updating. Batches are limited to 1000 items at a time. The creation option is asynchronous - rather than returning the newly created items, you will receive a report_id which can be used to track status of the requests as they are processed in our system. Reports are stored for 30 days.

The JSON objects passed in the array are the same as the ones listed in Create Or Update User.

HTTP Request

POST management/v1/users

Response Codes:

Deactivate User

Deactivate User Response

No Body returned

Deactivates all active programs for a given user placing them in an inactive state.

HTTP Request

DELETE management/v1/user/{userId}

Response Codes:

Group Management API

Get Groups

Get Groups Response

{
  "data": [
    {
      "id": "1234",
      "name": "Test Group 1"
    },
    {
      "id": "5678",
      "name": "Test Group 2"
    },
    {
      "id": "91011",
      "name": "Test Group 3"
    },
    {
      "id": "1213",
      "name": "Test Group 4"
    }
  ],
  "nextPageToken": "test_next_page_token", // only present when there is another page
  "previousPageToken": "test_previous_page_token" // only present when there is a previous page
}

Returns all groups. This is a paginated response - returning 100 results per page with optional page tokens to go to the next page and previous page if they exist.

HTTP Request

GET management/v1/groups

Request Params

Param Required Description
pageToken false The page token (taken from either nextPageToken, or previousPageToken provided in the response) for the page you want to retrieve.

Response Codes:

Create Or Update Group

Group Create/Update Request

{
  "id": "123",
  "name": "Test Group 1"
}

Group Create/Update Response

{
  "data": {
    "id": "123",
    "name": "Test Group 1"
  }
}

Endpoint for creating new groups or updating existing ones.

HTTP Request

POST management/v1/group

Create / Update Group Properties

Field Required Type Description
id true String ID of the group you wish to create or update.
name true String The human-readable name of the group you are creating or updating.

Response Codes:

Create Or Update Group Batch

Group Create Batch Request

[
  {
    "id": "123",
    "name": "Test Group 1"
  }
  // ...
]

Group Create Batch Response

{
  "data": {
    "reportId": "HG3SrEndQch8dAZbjwBV"
  }
}

Endpoint that allows you to pass a JSON Array of Group Request objects for creation. Batches are limited to 1000 items at a time. The creation option is asynchronous - rather than returning the newly created items, you will receive a report_id which can be used to track status of the requests as they are processed in our system. Reports are stored for 30 days.

HTTP Request

POST management/v1/groups

Response Codes:

Access Control

Many portions of our API use common access control models to control which users can access various objects (ex audiences or content items). The system works by defining grantees, permissions, and grants.

Grantee

A grantee represents something that is being granted permissions on an object. The types of grantees that currently exist are defined by the RestGranteeType enum:

RestGranteeType

Grantee Properties

The model used for a grantee has the following properties

Property Name Required Type Description
type true RestGranteeType What type of grantee this is.
userId false String Only used for USER and USER_IN_GROUP grantees. Defines what user the grantee refers to.
groupId false String Only used for GROUP, GROUP_ROLE, and USER_IN_GROUP grantees. Defines what group the grantee refers to.
groupRole false String Only used for GROUP_ROLE grantees. Defines what group role the grantee refers to. Valid values are "group_user" and "group_admin".

Note that the only required property for ORGANIZATION grantees is the type property.

Grantees

Portions of our API allow you to specify multiple Grantees. When this is the case, we utilize an object with a single grantees property.

Property Name Required Type Description
grantees true List of Grantee objects A list of grantees.

Permissions

What permissions are available depends on which portion of the API you are using. For example, our audiences API currently only supports READ permissions. See the docs for the specific resources you are accessing to see what permissions are available.

Grant

A grant is used to assign permissions to a grantee on a specific object. You'll notice after reading the Grantee documentation (located above) that a user can actually match multiple grantees. For example, a user would match a USER grantee that refers to that specific user, and it would also match an ORGANIZATION grantee (since that user is part of your organization). When multiple grants exist for a user on a single object (ex an audience), then the permissions are summed. In other words, the user has all permissions from those grants on the target object. The model used for a grant has the following properties

Property Name Required Type Description
grantee true Grantee The grantee that is assigned permissions on the target object.
permissions true String List What permissions the grantee has on the target object.
objectId false String The ID of the target object (the object that the grantee is receiving permissions on). This property usually only has a value if the grant is part of a response (instead of a request) or if the endpoint is a bulk endpoint. Otherwise, the resource in the endpoint's path is implicitly the target object.

Grants

Portions of our API allow you to specify multiple Grants. When this is the case, we utilize an object with a single grants property.

Property Name Required Type Description
grants true List of Grant objects A list of grants.

Content Management API

Get Repository

Get Repository Response

{
  "data": {
    "id": "repository_id",
    "name": "Repository Name",
    "description": " Repository Description",
    "isWritable": true,
    "fields": [
      {
        "name": "field_name",
        "isNullable": false,
        "type": "string" // can be "string", "number", "boolean", or "date_time"
      }
      // ...
    ]
  }
}

Returns a single repository and associated fields.

HTTP Request

GET management/v1/repository/{repositoryId}

URL Params

URL Param Required type Description
repositoryId true String The ID of the repository you are wanting to retrieve

Response Codes:

Get Repositories

Get Repositories Response

{
  "data": [
    {
      "id": "repository_id",
      "name": "Repository Name"
    }
    // ...
  ]
}

Returns a list of repositories.

HTTP Request

GET management/v1/repositories

Response Codes:

Get Item

Get Item Response

{
  "data": {
    "values": {
      "id": "item_id",
      "repository_field_name_1": "some value here",
      "repository_field_name_2": 42
      // ...
    }
  }
}

Returns a content item. The JSON object in the values field of the response will contains fields defined by the repository's fields.

HTTP Request

GET management/v1/repository/{repositoryId}/item/{itemId}

URL Params

URL Param Required type Description
repositoryId true String The ID of the repository you are wanting to retrieve
itemId true String The ID of the item you are wanting to retrieve

Response Codes:

Create Or Update Item

Create Or Update Item Request

{
  "values": {
    "id": "item_id",
    "repository_field_name_1": "some value here",
    "repository_field_name_2": 42
    // ...
  }
}

Create Or Update Item Response

{
  "data": {
    "values": {
      "id": "item_id",
      "repository_field_name_1": "some value here",
      "repository_field_name_2": 42
      // ...
    }
  }
}

Creates or updates a content item. The JSON request object should contain fields defined by the repository's fields.

HTTP Request

POST management/v1/repository/{repositoryId}/item

URL Params

URL Param Required type Description
repositoryId true String The ID of the repository in which you are wanting to create or update an item

Response Codes:

Create Or Update Item Batch

Batch Create Or Update Request

[
  {
    "values": {
      "id": "item_id",
      "repository_field_name_1": "some value here",
      "repository_field_name_2": 42
      // ...
    }
  }
  // ...
]

Create and Update Batch Response

{
  "data": {
    "reportId": "HG3SrEndQch8dAZbjwBV"
  }
}

This endpoint allows you to pass a JSON Array of Item Request objects for creation or updating. Batches are limited to 1000 items at a time. The creation option is asynchronous - rather than returning the newly created items, you will receive a report_id which can be used to track status of the requests as they are processed in our system. Reports are stored for 30 days.

The JSON objects passed in the array are the same as the ones listed in Create Or Update Item.

HTTP Request

POST management/v1/repository/{repositoryId}/items

URL Params

URL Param Required type Description
repositoryId true String The ID of the repository in which you are wanting to create or update items

Response Codes:

Delete Item

Delete Item Response

{
  "data": {
    "values": {
      "id": "item_id",
      "repository_field_name_1": "some value here",
      "repository_field_name_2": 42
      // ...
    }
  }
}

Deletes a content item.

HTTP Request

DELETE management/v1/repository/{repositoryId}/item/{itemId}

URL Params

URL Param Required type Description
repositoryId true String The ID of the repository in which you are wanting to delete an item
itemId true String The ID of the item you are wanting to delete

Response Codes:

Delete Item Batch

Batch Delete Request

[
  "item_id_1",
  "item_id_2"
  // ...
]

Delete Batch Response

{
  "data": {
    "reportId": "HG3SrEndQch8dAZbjwBV"
  }
}

This endpoint allows you to pass a JSON Array of Item IDs for deletion. Batches are limited to 1000 items at a time. The creation option is asynchronous - rather than returning the newly created items, you will receive a report_id which can be used to track status of the requests as they are processed in our system. Reports are stored for 30 days.

The JSON objects passed in the array are the same as the ones listed in Create Or Update Item.

HTTP Request

DELETE management/v1/repository/{repositoryId}/items

URL Params

URL Param Required type Description
repositoryId true String The ID of the repository in which you are wanting to delete items

Response Codes:

Content Access API V2

You can use our standard access control system to control access to content items. See the Access Control section for more details.

Get grants

Example grantee filter object

{
  "grantees": [
    {
      "type": "USER_IN_GROUP",
      "userId": "exampleUserId",
      "groupId": "exampleGroupId"
    },
    {
      "type": "USER_IN_GROUP",
      "userId": "exampleUserId",
      "groupId": "exampleGroupId"
    },
    {
      "type": "USER_IN_GROUP",
      "userId": "exampleUserId2",
      "groupId": "exampleGroupId"
    },
    {
      "type": "ORGANIZATION"
    },
    {
      "type": "USER",
      "userId": "exampleUserId3"
    },
    {
      "type": "GROUP",
      "groupId": "exampleGroupId3"
    },
    {
      "type": "GROUP_ROLE",
      "groupId": "exampleGroupId",
      "groupRole": "group_user"
    }
  ]
}

Get all grants for the content repository

GET management/v1/repository/{repositoryId}/grants

Get grants for the content repository, filtered by the example grantee filter object

// Note: If you percent decode the value for the filterByGrantee query parameter,
// you'll see that it decodes to the example grantee filter object.
GET management/v1/repository/{repositoryId}/grants?filterByGrantee=%7B%0D%0A++%22grantees%22%3A+%5B%0D%0A++++%7B%0D%0A++++++%22type%22%3A+%22USER_IN_GROUP%22%2C%0D%0A++++++%22userId%22%3A+%22exampleUserId%22%2C%0D%0A++++++%22groupId%22%3A+%22exampleGroupId%22%0D%0A++++%7D%2C%0D%0A++++%7B%0D%0A++++++%22type%22%3A+%22USER_IN_GROUP%22%2C%0D%0A++++++%22userId%22%3A+%22exampleUserId%22%2C%0D%0A++++++%22groupId%22%3A+%22exampleGroupId%22%0D%0A++++%7D%2C%0D%0A++++%7B%0D%0A++++++%22type%22%3A+%22USER_IN_GROUP%22%2C%0D%0A++++++%22userId%22%3A+%22exampleUserId2%22%2C%0D%0A++++++%22groupId%22%3A+%22exampleGroupId%22%0D%0A++++%7D%2C%0D%0A++++%7B%0D%0A++++++%22type%22%3A+%22ORGANIZATION%22%0D%0A++++%7D%2C%0D%0A++++%7B%0D%0A++++++%22type%22%3A+%22USER%22%2C%0D%0A++++++%22userId%22%3A+%22exampleUserId3%22%0D%0A++++%7D%2C%0D%0A++++%7B%0D%0A++++++%22type%22%3A+%22GROUP%22%2C%0D%0A++++++%22groupId%22%3A+%22exampleGroupId3%22%0D%0A++++%7D%2C%0D%0A++++%7B%0D%0A++++++%22type%22%3A+%22GROUP_ROLE%22%2C%0D%0A++++++%22groupId%22%3A+%22exampleGroupId%22%2C%0D%0A++++++%22groupRole%22%3A+%22group_user%22%0D%0A++++%7D%0D%0A++%5D%0D%0A%7D

Get grants for a specific content item

GET management/v1/repository/{repositoryId}/items/{itemId}/grants

Get grants for a specific content item, filtered by the example grantee filter object

// Note: If you percent decode the value for the filterByGrantee query parameter,
// you'll see that it decodes to the example grantee filter object.
GET management/v1/repository/{repositoryId}/items/{itemId}/grants?filterByGrantee=%7B%0D%0A++%22grantees%22%3A+%5B%0D%0A++++%7B%0D%0A++++++%22type%22%3A+%22USER_IN_GROUP%22%2C%0D%0A++++++%22userId%22%3A+%22exampleUserId%22%2C%0D%0A++++++%22groupId%22%3A+%22exampleGroupId%22%0D%0A++++%7D%2C%0D%0A++++%7B%0D%0A++++++%22type%22%3A+%22USER_IN_GROUP%22%2C%0D%0A++++++%22userId%22%3A+%22exampleUserId%22%2C%0D%0A++++++%22groupId%22%3A+%22exampleGroupId%22%0D%0A++++%7D%2C%0D%0A++++%7B%0D%0A++++++%22type%22%3A+%22USER_IN_GROUP%22%2C%0D%0A++++++%22userId%22%3A+%22exampleUserId2%22%2C%0D%0A++++++%22groupId%22%3A+%22exampleGroupId%22%0D%0A++++%7D%2C%0D%0A++++%7B%0D%0A++++++%22type%22%3A+%22ORGANIZATION%22%0D%0A++++%7D%2C%0D%0A++++%7B%0D%0A++++++%22type%22%3A+%22USER%22%2C%0D%0A++++++%22userId%22%3A+%22exampleUserId3%22%0D%0A++++%7D%2C%0D%0A++++%7B%0D%0A++++++%22type%22%3A+%22GROUP%22%2C%0D%0A++++++%22groupId%22%3A+%22exampleGroupId3%22%0D%0A++++%7D%2C%0D%0A++++%7B%0D%0A++++++%22type%22%3A+%22GROUP_ROLE%22%2C%0D%0A++++++%22groupId%22%3A+%22exampleGroupId%22%2C%0D%0A++++++%22groupRole%22%3A+%22group_user%22%0D%0A++++%7D%0D%0A++%5D%0D%0A%7D

Get grants response

{
  "data": {
    "grants": [
      {
        "grantee": {
          "type": "GROUP",
          "groupId": "exampleGroupId"
        },
        "permissions": [
          "READ"
        ],
        "objectId": "exampleItemId"
      },
      {
        "grantee": {
          "type": "USER",
          "userId": "exampleUserId"
        },
        "permissions": [
          "READ"
        ],
        "objectId": "exampleItemId2"
      }
    ]
  },
  "nextPageToken": "next_page_token", // only present when there is another page
  "previousPageToken": "previous_page_token" // only present when there is a previous page
}

You can retrieve existing grants for a specific content item, or across the entire content repository. You can also filter those grants by grantee.

HTTP Request

Across the entire repository: GET management/v1/repository/{repositoryId}/grants

For a specific item: GET management/v1/repository/{repositoryId}/items/{itemId}/grants

URL Params

URL Param Type Required Description
repositoryId String true The ID of the content repository whose grants you wish to view.
itemId String true (if using the item specific url) The ID of the content item that you would like to retrieve grants for.

Request Query Params

URL Param Type Required Description
filterByGrantee Grantees false A percent-encoded (as all query parameters should be) json object that specifies the grantees you would like to filter on. This object has a single grantees field that is a list of Grantee objects

Response properties

An example is shown to the right. The data property contains a json object holding all the grants you retrieved. See Access Control for full details. READ is the only valid permission for content access.

Field Nullable Type Description
grants false List of Grant objects A list of the grants retrieved.

Grant Upsert

Grant upsert request

{
  "grantee": {
    "type": "USER",
    "userId": "exampleUserId"
  },
  "permissions": ["READ"]
}

Grant upsert response

{
  "data": {
    "grantee": {
      "type": "USER",
      "userId": "exampleUserId"
    },
    "permissions": ["READ"],
    "objectId": "exampleContentItemId"
  }
}

You can upsert a grant on a content item. The upsert is performed based off of the grantee and content item ID. So only the grant for the given grantee/content-item-ID combo will be impacted by your request.

Note: Empty permissions lists are currently not supported by this endpoint. Use the DELETE endpoint instead.

HTTP Request

POST management/v1/repository/{repositoryId}/items/{itemId}/grant

URL Params

URL Param Type Required Description
repositoryId String true The ID of the content repository that the content item live in.
itemId String true The ID of the content item that you'd like to grant access to.

Request

The request body is a single Grant object. An example is shown to the right. See Grant for full details. READ is the only valid permission for content access.

Response

The data property contains the Grant object that you upserted. See Grant for full details. READ is the only valid permission for content access.

Batch Grant Upsert

Batch grant upsert request

{
  "grants": [
    {
      "grantee": {
        "type": "USER",
        "userId": "exampleUserId"
      },
      "permissions": ["READ"],
      "objectId": "exampleContentItemId1"
    },
    {
      "grantee": {
        "type": "GROUP",
        "groupId": "exampleGroupId"
      },
      "permissions": ["READ"],
      "objectId": "exampleContentItemId2"
    }
  ]
}

Batch grant upsert response

{
  "data": {
    "reportId": "HG3SrEndQch8dAZbjwBV"
  }
}

This endpoint allows you to pass a Grants object holding multiple grants for upserting. Batches are limited to 1000 grants at a time. The creation option is asynchronous - rather than returning the newly created grants, you will receive a report_id which can be used to track status of the requests as they are processed in our system. Reports are stored for 30 days. See the Batch Report API docs for more details.

Note: Empty permissions lists are currently not supported by this endpoint. Use the DELETE endpoint instead.

HTTP Request

POST management/v1/repository/{repositoryId}/grants

URL Params

URL Param Type Required Description
repositoryId String true The ID of the content repository whose grants you would like to update.

Request

The request body is our standard Grants object. See Access Control for more details.

Delete grants

Optional request body to delete grants for specific grantees

// This request body is the same whether you are deleting
// grants across the entire repository or for a specific
// item.
{
  "grantees": [
    {
      "type": "USER_IN_GROUP",
      "userId": "exampleUserId",
      "groupId": "exampleGroupId"
    },
    {
      "type": "USER_IN_GROUP",
      "userId": "exampleUserId",
      "groupId": "exampleGroupId"
    },
    {
      "type": "USER_IN_GROUP",
      "userId": "exampleUserId2",
      "groupId": "exampleGroupId"
    },
    {
      "type": "ORGANIZATION"
    },
    {
      "type": "USER",
      "userId": "exampleUserId3"
    },
    {
      "type": "GROUP",
      "groupId": "exampleGroupId3"
    },
    {
      "type": "GROUP_ROLE",
      "groupId": "exampleGroupId",
      "groupRole": "group_user"
    }
  ]
}

Delete grants response

{
  "data": {
    "numberOfGrantsDeleted": 42
  }
}

You can delete grants for a specific content item, or across the entire content repository. You can also delete grants for specific grantees by providing a Grantees object as the request body.

HTTP Request

Across the entire repository: DELETE management/v1/repository/{repositoryId}/grants

For a specific item: DELETE management/v1/repository/{repositoryId}/item/{itemId}/grants

URL Params

URL Param Type Required Description
repositoryId String true The ID of the content repository whose grants you want to delete.
itemId String true (if using the item specific url) The ID of the content item that you would like to delete grants for.

Request Body

The request body is optional and is only needed if you want to limit the delete operation to specific grantees. The body is our standard Grantees object.

Response properties

An example is shown to the right. The data property contains a json object with a single property:

Field Nullable Type Description
numberOfGrantsDeleted false Int The number of grants that were deleted.

Content Access API V1 (Deprecated)

This API is now deprecated. Use Content Access API V2 instead.

Access Basics

For each content item your organization uploads you will need corresponding access records. Access records define who can use the item for their ad campaigns and whether or not they have the ability to edit the item after it is in the system. Content Items have a one to many relationship to access records, although it is completely valid to have a content item only accessible by a single user.

Access to a given content item can be defined at the following levels: - User based - Group Based - Group and Role based

The ability to edit the content item can be granted by passing true for the canEdit flag.

Get Access Records associated to a repository

Access Records Response

{
    "data": [
        {
            "contentItemId": "exampleId1",
            "userId": "seattle_user_1",
            "groupId": "seattle_office",
            "canEdit": false,
            "role": "group_user",
            "deleted": false
        }, // more records if applicable
    ],
    "nextPageToken": "next_page_token", // only present when there is another page
    "previousPageToken": "previous_page_token" // only present when there is a previous page
}

If you decline to pass query params - this call will return all access records associated with a given repository. Otherwise it will return return a subset based on the provied query parameters.

Response Codes:

HTTP Request

GET management/v1/repository/{repositoryId}/access

URL Params

URL Param Type Required Description
repositoryId String true The ID of the content repository whose access records you wish to view.

Request Query Params

URL Param Type Required Description
userId string false Query for all records that match the provided userId.
groupId string false Query for all records that match the provided groupId, note that this will return records that may or may not have a userId associated with them.
role string false Query for all records that match the provided role. If this is omitted, all records will be return according to the other criteria provided.
deletedOnly boolean false When this is passed we will only return items that have been deleted.

Get Access Records associated to a repository and content item

Access Records Response

{
    "data": [
        {
            "contentItemId": "exampleId1",
            "userId": "seattle_user_1",
            "groupId": "seattle_office",
            "canEdit": false,
            "role": "group_user",
            "deleted": false
        }, // more records if applicable
    ],
    "nextPageToken": "next_page_token", // only present when there is another page
    "previousPageToken": "previous_page_token" // only present when there is a previous page
}

HTTP Request

GET management/v1/repository/{repositoryId}/access/item/{contentItemId}

Response Codes:

URL Params

URL Param Type Required Description
repositoryId string true The ID of the content repository whose access records you wish to view
contentItemId string true The ID of the content item whose access records you wish to view

Request Query Params

URL Param Type Required Description
userId string false Query for all records that match the provided userId.
groupId string false Query for all records that match the provided groupId, note that this will return records that may or may not have a userId associated with them.
role string false Query for all records that match the provided role. If this is omitted, all records will be return according to the other criteria provided.
deletedOnly boolean false When this is passed we will only return items that have been deleted.

Create/Update a single access record

Access Record Request Payload: Every group_user in the group seattle_office can use this content item. Can not edit.

{
    "contentItemId": "exampleId1",
    "userId": null,
    "groupId": "seattle_office",
    "canEdit": false,
    "role": "group_user"
}

Access Record Request Payload: User seattle_user_1, in group seattle_office has is able to use this content item. Can not edit.

{
    "contentItemId": "exampleId1",
    "userId": "seattle_user_1",
    "groupId": "seattle_office",
    "canEdit": false,
    "role": "group_user"
}

Access Record Response Payload

{
    "data": {
        "contentItemId": "exampleId1",
        "userId": "seattle_user_1",
        "groupId": "seattle_office",
        "canEdit": false,
        "role": "group_user",
        "deleted": false
    }
}

HTTP Request

POST management/v1/repository/{repositoryId}/access/item

Response Codes:

Create / Update Access Record Request fields

Field Nullable Type Description
contentItemId false string The content item id for which this access record is responsible for.
userId true string If you would like access to be constrained to a specifc user, set this field. Otherwise pass null.
groupId false string The group associated to this content item. If userId is null, then all members of the group (with the given role) have access to the content item
role false string The role this access row applies too. Valid roles are group_user, group_admin. If you do not want to provide access based on role - pass any
canEdit false boolean Sets whether or not the users this access record applies too are allowed to edit the content.

Create / Update Access Record Batch

Batch Create Or Update Request

[
    {
        "contentItemId": "exampleId1",
        "userId": "seattle_user_1",
        "groupId": "seattle_office",
        "canEdit": false,
        "role": "group_user"
    },
    {
        "contentItemId": "exampleId2",
        "userId": "seattle_user_1",
        "groupId": "seattle_office",
        "canEdit": false,
        "role": "group_admin"
    }
  // ...
]

Create and Update Batch Response

{
  "data": {
    "reportId": "HG3SrEndQch8dAZbjwBV"
  }
}

This endpoint allows you to pass a JSON Array of Access Record Request objects for creation or updating. Batches are limited to 1000 items at a time. The creation option is asynchronous - rather than returning the newly created items, you will receive a report_id which can be used to track status of the requests as they are processed in our system. Reports are stored for 30 days.

The JSON objects passed in the array are the same as the ones listed in Create Or Update Access Record.

HTTP Request

POST management/v1/repository/{repositoryId}/access/items

URL Params

URL Param Required type Description
repositoryId true String The ID of the repository in which you are wanting to create or update items

Response Codes:

Delete Access Record

Remove Single Access for a given Content Item Record Request Payload (Request Includes /{contentItemId}).

{
    "userId": "seattle_user_2",
    "groupId": "seattle_office",
    "role": "group_admin"
}

Remove All Access Records Associated For A Given Content Item and groupId Request Payload (Request Includes /{contentItemId}).

{
    "userId": null,
    "groupId": "seattle_office",
    "role": null
}

Remove All Access Records Associated For A Given Content Item Request Payload (Request Includes /{contentItemId}).

{
    "userId": null,
    "groupId": null,
    "role": null
}

Remove All Access Records For A Given Repository Matching a Specific userId (Request Includes /{contentItemId}).

{
    "userId": "example_user_id",
    "groupId": null,
    "role": null
}

Remove All Access Records For A Given Repository Matching a Specific groupId (Request Does Not Include /{contentItemId}).

{
    "userId": null,
    "groupId": "seattle_office",
    "role": null
}

Remove All Access Records For A Given Repository Matching a Specific groupId and userId (Request Does Not Include /{contentItemId}).

{
    "userId": "example_user_id",
    "groupId": "seattle_office",
    "role": null
}

Remove All Access Records In a Repository (Request Does Not Include /{contentItemId})

{
    "userId": null,
    "groupId": null,
    "role": null
}

Response

{
    "data": {
        "numberOfAccessRecordsDeleted": 5
    }
}

Removing access follows a very similar pattern to querying for them. One important difference is that you must always pass each field, with null being a valid value. Example: If you wanted to remove all the access records for a given contentItemId then you would need to set userId, groupId and role as null. If you omit contentItemId the operation is applied against the entire repository. If your query does not match any access records the response will indicate 0.

HTTP Request

DELETE management/v1/repository/{repositoryId}/access/item/{contentItemId}, DELETE management/v1/repository/{repositoryId}/access

Response Codes:

URL Params

URL Param Type Required Description
contentItemId string false The Id of the content item whose access records you are removing.

Delete Access Record Fields

Field Nullable Type Description
userId true string The user id for the associated access record.
groupId true string The group id for the associated access record.
role true string The role for the associated access record.

Batch Report API

Get Report

Get Report Response

{
  "data": {
    "totalItems": 750,
    "remainingItems": 500,
    "completedItems": 250,
    "successfulItems": 250,
    "errorItems": 0,
    "isCompleted": false
  }
}

For batch endpoints we return a report_id string instead of the created objects. This endpoint allows you to view the status of a given batch. We retain this data for 30 days after the report was generated.

HTTP Request

GET management/v1/items/report/{reportId}

URL Params

URL Param Required type Description
reportId true String The ID of the report you are wanting to retrieve

Response Codes:

200 OK 404 NOT FOUND - When we are unable to locate a report with that ID.

Get Errors Batch Rquests

Get Report Response

{
  "data": [
    {
      "input": {
        "id": "test_user_id",
        "name": "Test User",
        "email": "example@evocalize.com",
        "groups": [
          {
            "id": "seattle_office",
            "name": "Seattle Office",
            "role": "group_admin"
          }
        ]
      },
      "errorMessage":"Duplicate user create request detected: user with example@evocalize.com has already been associated to another user id.",
      "restErrorCode": "EV_BAD_REQUEST_DUPLICATE" //this is not always present. 
    }
  ],
  "nextPageToken": "test_next_page_token", // only present when there is another page
  "previousPageToken": "test_previous_page_token" // only present when there is a previous page
}

This endpoint displays error information for items in a given batch (retrieved by passing the report_id similar to the above call) that were not successful. The error messages and error codes generally are the ones you would see if using the non batch endpoints. For debugging purposes we return the input used so you can amend any mistakes. If there are no errors associated with a report this endpoint will return an empty array for the data field.

HTTP Request

GET management/v1/items/report/{reportId}/errors

URL Params

URL Param Required type Description
reportId true String The ID of the report you are wanting to retrieve

Response Codes:

200 OK

Orders

Place Purchase Order

Place Purchase Order Request

{
  "userId": "test_user_id",
  "groupId": "test_group_id",
  "productCode": "pid_1234567890",
  "orderType": "purchase",
  "paymentAmount": 100,
  "schedule": {
    "startTimestamp": 1735718400,
    "endTimestamp": 1738396800
  },
  "contentItemIds": [],
  "variableValues": {
    "accountId": "1234567890",
    "pageId": "1234567890",
    "headline": "headline test",
    "bodyText": "body text test",
    "image": "https://image.test",
    ...
  }
}

Place Purchase Order Response

{
  "data": {
    "id": "1234567890",
    "userId": "test_user_id",
    "groupId": "test_group_id",
    "productCode": "pid_1234567890",
    "status": "pending",
    "orderType": "purchase",
    "paymentAmount": 100,
    "schedule": {
      "startTimestamp": 1735718400,
      "endTimestamp": 1738396800
    },
    "contentItemIds": [],
    "variableValues": {
      "accountId": "1234567890",
      "headline": "headline test",
      "bodyText": "body text test",
      "image": "https://image.test",
      ...
    }
  }
}

This endpoint allows you to place a one-time purchase order.

HTTP Request

POST management/v1/order

Place Purchase Order Request Properties

Field Required Type Description
userId true String The ID of the user placing the order.
groupId true String The ID of the group associated with the user.
productCode true String Code identifying the product for the order.
orderType true String Must be set to "purchase" for one-time purchase orders.
paymentAmount true Float The total payment amount, in USD, for the order.
schedule true Object Contains scheduling information for the order.
schedule.startTimestamp true Int Start time of the purchase period in Pacific Time (Unix timestamp format in seconds).
schedule.endTimestamp true Int End time of the purchase period in Pacific Time (Unix timestamp format in seconds).
contentItemIds false String List An array of content item IDs representing specific content items to include in the order.
variableValues false Map A map providing creative data required to supply the product.

General Constraints

Scheduling

Payment

Content

Response Codes:

Place Subscription Order

Place Subscription Order Request

{
  "userId": "test_user_id",
  "groupId": "test_group_id",
  "productCode": "pid_1234567890",
  "orderType": "subscription",
  "paymentAmount": 100,
  "schedule": {
    "startTimestamp": 1735718400
  },
  "contentItemIds": [],
  "variableValues": {
    "accountId": "1234567890",
    "headline": "headline test",
    "bodyText": "body text test",
    "image": "https://image.test",
    ...
  }
}

Place Subscription Order Response

{
  "data": {
    "id": "1234567890",
    "userId": "test_user_id",
    "groupId": "test_group_id",
    "productCode": "pid_1234567890",
    "status": "pending",
    "orderType": "subscription",
    "paymentAmount": 100,
    "schedule": {
      "startTimestamp": 1735718400
    },
    "contentItemIds": [],
    "variableValues": {
      "accountId": "1234567890",
      "headline": "headline test",
      "bodyText": "body text test",
      "image": "https://image.test",
      ...
    }
  }
}

This endpoint allows you to place a subscription order, which is scheduled to start at the beginning of the month, runs until the specified monthly budget is exhausted, and renews at the start of each new month.

HTTP Request

POST management/v1/order

Place Subscription Order Request Properties

Field Required Type Description
userId true String The ID of the user placing the order.
groupId true String The ID of the group associated with the user.
productCode true String Code identifying the product for the order.
orderType true String Must be set to "subscription" for subscription orders.
paymentAmount true Float The total payment amount, in USD, for the order.
schedule true Object Contains scheduling information for the order.
schedule.startTimestamp true Int Start time of the subscription period in Pacific Time (Unix timestamp format in seconds).
contentItemIds false String List An array of content item IDs representing specific content items to include in the order.
variableValues false Map A map providing creative data required to supply the product.

General Constraints

Scheduling

Payment

Content

Response Codes:

Edit Purchase Order

Edit Purchase Order Request - Adjust Payment Amount

{
  "paymentAmount": 200
}

Edit Purchase Order Response - Adjust Payment Amount

{
  "data": {
    "id": "1234567890",
    "userId": "test_user_id",
    "groupId": "test_group_id",
    "productCode": "pid_1234567890",
    "status": "pending",
    "orderType": "purchase",
    "paymentAmount": 200,
    "schedule": {
      "startTimestamp": 1735718400,
      "endTimestamp": 1738396800
    },
    "contentItemIds": [],
    "variableValues": {
      "accountId": "1234567890",
      "headline": "headline test",
      "bodyText": "body text test",
      "image": "https://image.test",
      ...
    }
  }
}

Edit Purchase Order Request - Adjust Schedule Start

 {
  "schedule": {
    "startTimestamp": 1735804380
  }
}

Edit Purchase Order Response - Adjust Schedule Start

{
  "data": {
    "id": "1234567890",
    "userId": "test_user_id",
    "groupId": "test_group_id",
    "productCode": "pid_1234567890",
    "status": "pending",
    "orderType": "purchase",
    "paymentAmount": 100,
    "schedule": {
      "startTimestamp": 1735804380,
      "endTimestamp": 1738396800
    },
    "contentItemIds": [],
    "variableValues": {
      "accountId": "1234567890",
      "headline": "headline test",
      "bodyText": "body text test",
      "image": "https://image.test",
      ...
    }
  }
}

Edit Purchase Order Request - Adjust Schedule End

 {
  "schedule": {
    "endTimestamp": 1738482780
  }
}

Edit Purchase Order Response - Adjust Schedule End

{
  "data": {
    "id": "1234567890",
    "userId": "test_user_id",
    "groupId": "test_group_id",
    "productCode": "pid_1234567890",
    "status": "pending",
    "orderType": "purchase",
    "paymentAmount": 100,
    "schedule": {
      "startTimestamp": 1735718400,
      "endTimestamp": 1738482780
    },
    "contentItemIds": [],
    "variableValues": {
      "accountId": "1234567890",
      "headline": "headline test",
      "bodyText": "body text test",
      "image": "https://image.test",
      ...
    }
  }
}

Edit Purchase Order Request - Adjust Variable Value

 {
  "variableValues": {
    "headline": "headline test updated",
    ...
  }
}

Edit Purchase Order Response - Adjust Variable Value

{
  "data": {
    "id": "1234567890",
    "userId": "test_user_id",
    "groupId": "test_group_id",
    "productCode": "pid_1234567890",
    "status": "pending",
    "orderType": "purchase",
    "paymentAmount": 100,
    "schedule": {
      "startTimestamp": 1735718400,
      "endTimestamp": 1738396800
    },
    "contentItemIds": [],
    "variableValues": {
      "accountId": "1234567890",
      "headline": "headline test updated",
      "bodyText": "body text test",
      "image": "https://image.test",
      ...
    }
  }
}

This endpoint allows you to edit a one-time purchase order.

HTTP Request

PUT management/v1/order/{orderId}

URL Param Required Type Description
orderId true String The ID of the purchase order to be edited.

Edit Purchase Order Request Properties

Field Required Type Description
paymentAmount false Float The total payment amount, in USD, for the order.
schedule false Object Contains scheduling information for the order.
schedule.startTimestamp false Int Start time of the purchase period in Pacific Time (Unix timestamp format in seconds).
schedule.endTimestamp false Int End time of the purchase period in Pacific Time (Unix timestamp format in seconds).
variableValues false Map A map providing new creative data required to supply the product.

General Constraints

Scheduling

Payment

Content

Response Codes:

Edit Subscription Order

Edit Subscription Order Request - Adjust Payment Amount

{
  "paymentAmount": 200
}

Edit Subscription Order Response - Adjust Payment Amount

{
  "data": {
    "id": "1234567890",
    "userId": "test_user_id",
    "groupId": "test_group_id",
    "productCode": "pid_1234567890",
    "status": "pending",
    "orderType": "subscription",
    "paymentAmount": 200,
    "schedule": {
      "startTimestamp": 1735718400
    },
    "contentItemIds": [],
    "variableValues": {
      "accountId": "1234567890",
      "headline": "headline test",
      "bodyText": "body text test",
      "image": "https://image.test",
      ...
    }
  }
}

Edit Subscription Order Request - Adjust Schedule Start

 {
  "schedule": {
    "startTimestamp": 1735804380
  }
}

Edit Subscription Order Response - Adjust Schedule Start

{
  "data": {
    "id": "1234567890",
    "userId": "test_user_id",
    "groupId": "test_group_id",
    "productCode": "pid_1234567890",
    "status": "pending",
    "orderType": "subscription",
    "paymentAmount": 100,
    "schedule": {
      "startTimestamp": 1735804380
    },
    "contentItemIds": [],
    "variableValues": {
      "accountId": "1234567890",
      "headline": "headline test",
      "bodyText": "body text test",
      "image": "https://image.test",
      ...
    }
  }
}

Edit Subscription Order Request - Adjust Variable Value

 {
  "variableValues": {
    "headline": "headline test updated",
    ...
  }
}

Edit Subscription Order Response - Adjust Variable Value

{
  "data": {
    "id": "1234567890",
    "userId": "test_user_id",
    "groupId": "test_group_id",
    "productCode": "pid_1234567890",
    "status": "pending",
    "orderType": "subscription",
    "paymentAmount": 100,
    "schedule": {
      "startTimestamp": 1735718400
    },
    "contentItemIds": [],
    "variableValues": {
      "accountId": "1234567890",
      "headline": "headline test updated",
      "bodyText": "body text test",
      "image": "https://image.test",
      ...
    }
  }
}

This endpoint allows you to edit a subscription order.

HTTP Request

PUT management/v1/order/{orderId}

URL Params

URL Param Required Type Description
orderId true String The ID of the subscription order to be edited.

Edit Subscription Order Request Properties

Field Required Type Description
paymentAmount false Float The total payment amount, in USD, for the order.
schedule false Object Contains scheduling information for the order.
schedule.startTimestamp false Int Start time of the subscription period in Pacific Time (Unix timestamp format in seconds).
variableValues false Map A map providing new creative data required to supply the product.

General Constraints

Scheduling

Payment

Content

Response Codes:

Cancel Order

Cancel Order Order Response

{
  "data": {
    "orderId": "1234567890",
    "refundAmount": 90
  }
}

This endpoint allows you to cancel a purchase or subscription order.

HTTP Request

POST management/v1/order/{orderId}/cancel

URL Params

URL Param Required Type Description
orderId true String The ID of the order to be cancelled.

Place Purchase Order Response Properties

Field Nullable Type Description
orderId false String The ID of the order that was cancelled
refundAmount false Float The refunded amount of the cancelled order.

Response Codes:

Get Order By ID

Returns the order information given an order ID.

Get Order By ID Response - Purchase

{
  "data": {
    "id": "1234567890",
    "userId": "test_user_id",
    "groupId": "test_group_id",
    "productCode": "pid_1234567890",
    "status": "active",
    "orderType": "purchase",
    "paymentAmount": 100,
    "schedule": {
      "startTimestamp": 1735718400,
      "endTimestamp": 1738396800
    },
    "contentItemIds": [],
    "variableValues": {
      "accountId": "1234567890",
      "headline": "headline test",
      "bodyText": "body text test",
      "image": "https://image.test",
      ...
    }
  }
}

Get Order By ID Response - Subscription

{
  "data": {
    "id": "1234567890",
    "userId": "test_user_id",
    "groupId": "test_group_id",
    "productCode": "pid_1234567890",
    "status": "active",
    "orderType": "subscription",
    "paymentAmount": 100,
    "schedule": {
      "startTimestamp": 1735718400
    },
    "contentItemIds": [],
    "variableValues": {
      "accountId": "1234567890",
      "headline": "headline test",
      "bodyText": "body text test",
      "image": "https://image.test",
      ...
    },
    "subscriptionDetails": {
      "renewsOnTimestamp": 1735718400,
      "endsOnTimestamp": null,
      "subscriptionAmount": 100,
      "status": "active"
    }
  }
}

HTTP Request

GET management/v1/order/{orderId}

URL Params

URL Param Required type Description
orderId true String The ID of the order you are wanting to retrieve.

Get Order By ID Response Properties

Field Nullable Type Description
id false String The ID of the order.
userId false String The ID of the user associated to the order.
groupId false String The ID of the group associated the user.
productCode false String Code identifying the product for the order.
orderType false String The type of order which can be purchase or subscription.
paymentAmount false Float The total payment amount, in USD, for the order.
status false String The status of the order.
schedule false Object Contains scheduling information for the order.
schedule.startTimestamp false Int Start time of the purchase/subscription period in Pacific Time (Unix timestamp format in seconds).
schedule.endTimestamp true Int End time of the purchase period in Pacific Time (Unix timestamp format in seconds).
contentItemIds false String List An array of content item IDs representing specific content items included in the order.
variableValues false Map A map containing the creative data required to supply the product.
subscriptionDetails true Object Details related to the subscription if the order is a subscription.

Order Statuses:

Subscription Details Response Properties

Field Nullable Type Description
renewsOnTimestamp true Int Renewal time of the subscription period in Pacific Time (Unix timestamp format in seconds).
endsOnTimestamp true Int End time of the subscription period in Pacific Time (Unix timestamp format in seconds).
subscriptionAmount false Float The payment amount for the subscription interval.
status false String The status of the subscription interval.

Subscription Detail Statuses:

Response Codes:

Get Order Refund Preview By ID

Returns the order refund preview information given an order ID.

Get Order Refund Preview By ID Response

{
  "data": {
    "orderId": "1234567890",
    "subTotal": 100.0000,
    "cancellationFee": 0.0000,
    "totalRefund": 100.0000,
    "cancellationType": "immediate",
    "daysRemaining": 30,
    "nextIntervalPaidAmount": 0
  }
}

HTTP Request

GET management/v1/order/{orderId}/refundpreview

URL Params

URL Param Required type Description
orderId true String The ID of the order you are wanting to preview refund.

Get Order By ID Response Properties

Field Nullable Type Description
orderId false String The ID of the order.
subTotal false Float The refund amount of the order before applying fees.
cancellationFee false Float The cancellation fee of the order.
totalRefund false Float The refund amount of the order after applying fees.
cancellationType false String The type of order cancellation which can be immediate or deferred.
daysRemaining false Int The remaining days for this order.
nextIntervalPaidAmount true String The future interval amount to be refunded without fee.

Response Codes:

Webhooks

Client Leads Webhook

Evocalize can notify your organization via webhook any time a new lead is ingested from an upstream platform such as Facebook or Google. Upon notification from the upstream platform that new lead data has been created, we combine that with Evocalize data and your data, and send it to you, allowing you to handle leads in near real-time.

Setup

You will need to work with your account manager and supply Evocalize with an endpoint url where you would like to be notified with the payload specified below. Your endpoint url must use SSL (https) and accept a POST. You will need to have a ClientKeyID and a ClientSecret. These are the same values that you will use to call our API for other operations.

Policies

Headers

Signature Validation - Optional

Signature validation

// Concatenate all the parts
val toValidate = StringBuilder()
    .append(request.servletPath)
    .append("\n")
    .append(request.body())
    .append("\n")
    .append(request.headers["X-Evocalize-Timestamp"])
    .append("\n")
    .append(myClientSecret)
    .toString()

// expectedSignature will match request.headers["X-Evocalize-Signature"]
val expectedSignature = Hashing.sha256().hashString(toValidate, Charsets.UTF_8)

For extra security, partners may have the need or desire to validate each individual request signature. Validating the request signature provides extra security over relying solely on the ClientKeyId because it uses the ClientSecret above. The ClientSecret is never sent over the wire. The methodology is simple. Join the following values into one string, separated by a newline, then hash them using SHA-256

Since we require the use of the https protocol for our webhooks, it is up to each partner to choose if they would like to validate the signature.

Payload

Payload Example (Facebook Lead)

{
  "leads": [
    {
      "id": "facebook:1584659102387",
      "facebook": {
        "summary": {
          "leadgenId": "1584659102387",
          "pageId": "1584659102389",
          "leadFormId": "1584659102390",
          "adgroupId": "1584659102388",
          "adId": "1584659102388",
          "retailerItemId": "1584659102388",
          "createdAtEpochSeconds": 1584659108
        },
        "leadForm": [
          {
            "name": "field_one",
            "values": [
              "value one"
            ]
          }
        ],
        "leadFormDisclaimerResponses": [
          {
            "consentText": "Example Consent Text",
            "isConsentChecked": true
          }
        ]
      },
      "content": [
        [
          {
            "friendlyName": "Catalog Field Name",
            "name": "columnName",
            "value": "field value"
          }
        ]
      ],
      "program": {
        "projectId": 643545619583019092,
        "programId": 643545619499133011,
        "programName": "programName-1584659102374",
        "programDescription": "verbose program description-1584659102375",
        "programVariables": {
          "customValue1": "custom value for your application",
          "customValue2": 42
        }
      },
      "order": {
        "architectureName": "Example Architecture Name",
        "architectureId": 643545620052781143,
        "productName": "Single Image Ad",
        "productId": 643545619583019092,
        "orderId": 643545620052781143,
        "userId": "email-1584659102362@example.com",
        "groupId": "3775e2cc-e8f0-4402-b947-e8f2112fc1b4",
        "orderItem": {
          "orderItemId": 643545620774201440
        }
      }
    }
  ]
}

Payload Example (Google Lead)

{
  "leads": [
    {
      "id": "google:1584659102387",
      "google": {
        "summary": {
          "campaignId": 1652440203600,
          "formId": 1652440203601,
          "adgroupId": 1652440203602,
          "creativeId": 1652440203603,
          "gclId": "gclId-1652440203604",
          "leadId": "1652440203598"
        },
        "leadForm": [
          {
            "name": "field_one",
            "values": [
              "value one"
            ]
          }
        ]
      },
      "content": [
        [
          {
            "friendlyName": "Catalog Field Name",
            "name": "columnName",
            "value": "field value"
          }
        ]
      ],
      "program": {
        "projectId": 643545619583019092,
        "programId": 643545619499133011,
        "programName": "programName-1584659102374",
        "programDescription": "verbose program description-1584659102375",
        "programVariables": {
          "customValue1": "custom value for your application",
          "customValue2": 42
        }
      },
      "order": {
        "architectureName": "Example Architecture Name",
        "architectureId": 643545620052781143,
        "productName": "Single Image Ad",
        "productId": 643545619583019092,
        "orderId": 643545620052781143,
        "userId": "email-1584659102362@example.com",
        "groupId": "3775e2cc-e8f0-4402-b947-e8f2112fc1b4",
        "orderItem": {
          "orderItemId": 643545620774201440
        }
      }
    }
  ]
}

Payload Example (TikTok Lead)

{
  "leads": [
    {
      "id": "tikTok:8a2bd6e1-5bfb-4e4e-b6fa-cc48c737bd8a",
      "tikTok": {
        "summary": {
          "formId": 1652440203717,
          "campaignId": 1652440203718,
          "adGroupId": 1652440203720,
          "adId": 1652440203722,
          "createdAtEpochSeconds": 1652440203724
        },
        "leadForm": [
          {
            "name": "field_one",
            "values": [
              "value_one"
            ]
          }
        ]
      },
      "content": [
        [
          {
            "friendlyName": "Catalog Field Name",
            "name": "columnName",
            "value": "field value"
          }
        ]
      ],
      "program": {
        "projectId": 643545619583019092,
        "programId": 643545619499133011,
        "programName": "programName-1584659102374",
        "programDescription": "verbose program description-1584659102375",
        "programVariables": {
          "customValue1": "custom value for your application",
          "customValue2": 42
        }
      },
      "order": {
        "architectureName": "Example Architecture Name",
        "architectureId": 643545620052781143,
        "productName": "Single Image Ad",
        "productId": 643545619583019092,
        "orderId": 643545620052781143,
        "userId": "email-1584659102362@example.com",
        "groupId": "3775e2cc-e8f0-4402-b947-e8f2112fc1b4",
        "orderItem": {
          "orderItemId": 643545620774201440
        }
      }
    }
  ]
}

Special consideration should be taken not to fail if a new field is present in your data that you did not expect. We will notify you when a field is removed from our specification, but we will not notify you when a field is added to the specification. If a field is removed from the specification, the payloadVersion will increment.

The potential values of leadForm and content depends upon your imported data and program setup. Your account representative can help with this.

Field Nullable Type Description
leads false array A list of lead data.
leads[] false object
leads[].id false string The id of this lead.
leads[].facebook true object Facebook data for this lead. Details for this object are provided below.
leads[].google true object Google data for this lead. Details for this object are provided below.
leads[].tikTok true object TikTok data for this lead. Details for this object are provided below.
leads[].content false array An array of content items associated with this ad.
leads[].content[] false array An array of content fields for the item.
leads[].content[][] false object
leads[].content[][].friendlyName true string The friendly name of this content field.
leads[].content[][].name false string The actual name of this content field. It will be in snake_case.
leads[].content[][].value true string The value for this content field. It could be null.
leads[].program false object Details about the program that published the ad associated with this lead.
leads[].program.projectId false long The evocalize project id associated with this lead.
leads[].program.programId false long The evocalize program id associated with this lead.
leads[].program.programName false long The name of the program that published this ad.
leads[].program.programDescription true string The description of the program that published this ad.
leads[].program.programVariables* true object A key-value map containing values specific to your application.
leads[].order true object
leads[].order.architectureId false long The id of the architecture associated to the order.
leads[].order.archietctureName false string The name of the architecture associated to the order.
leads[].order.productName false string The name of the product associated to the order.
leads[].order.productId false long The id of the product associated to the order.
leads[].order.orderId false long The order id associated with the program.
leads[].order.userId false string The user id associated with this order. This is the id in your system.
leads[].order.groupId false string The group id associated with this order. This is the id in your system.
leads[].order.orderItem false object
leads[].order.orderItem.orderItemId false long The order item id associated with the order project.

*If you have values that you need our API to return for this field, please contact your Evocalize account representative.

Facebook Lead Data

Field Nullable Type Description
leads[].facebook.summary false object Summary data for this Facebook lead.
leads[].facebook.summary.leadgenId false string Facebook's leadgen_id.
leads[].facebook.summary.pageId false string The Facebook page that the ad for this lead is associated with.
leads[].facebook.summary.leadFormId false string The Facebook lead form id associated with this lead.
leads[].facebook.summary.adgroupId false string The Facebook adgroup id associated with this lead.
leads[].facebook.summary.adId false string The Facebook ad id associated with this lead.
leads[].facebook.summary.retailerItemId false string (Dynamic Ads Only) Id of the content (in catalog) that the user clicked on before submitting their lead.
leads[].facebook.summary.createdAtEpochSeconds false long The time this lead was created, as a unix timestamp in seconds.
leads[].facebook.leadForm false array Values that a person filled out on the lead form.
leads[].facebook.leadForm[] false object
leads[].facebook.leadForm[].name false string The name of the Facebook lead form field.
leads[].facebook.leadForm[].values false array An array of the values the user filled out.
leads[].facebook.leadForm[].values[] false string Each element is a value that the end user selected or entered. In most cases there is only one element.
leads[].facebook.leadFormDisclaimerResponses true array Values that a person filled out on the lead form custom disclaimer.
leads[].facebook.leadFormDisclaimerResponses[] false object
leads[].facebook.leadFormDisclaimerResponses[].consentText false string The consent text of the Facebook lead form custom disclaimer checkbox.
leads[].facebook.leadFormDisclaimerResponses[].isConsentChecked false boolean Indicates if the Facebook lead form custom disclaimer checkbox was checked.

Google Lead Data

Field Nullable Type Description
leads[].google.summary false object Summary data for this Google lead.
leads[].google.summary.campaignId false string Google's campaign ID.
leads[].google.summary.formId false string The Google lead form ID.
leads[].google.summary.adgroupId false string The Google ad group ID.
leads[].google.summary.creativeId true string The Google creative ID.
leads[].google.summary.gclId false string The Google click id .
leads[].google.summary.leadId false long The Google lead ID.
leads[].google.leadForm false array Values that a person filled out on the lead form.
leads[].google.leadForm[] false object
leads[].google.leadForm[].name false string The name of the facebook lead form field.
leads[].google.leadForm[].values false array An array of the values the user filled out.
leads[].google.leadForm[].values[] false string Each element is a value that the end user selected or entered. In most cases there is only one element.

TikTok Lead Data

Field Nullable Type Description
leads[].tikTok.summary false object Summary data for this facebook lead.
leads[].tikTok.summary.leadgenId false string Facebook's leadgen_id.
leads[].tikTok.summary.pageId false string The facebook page that the ad for this lead is associated with.
leads[].tikTok.summary.leadFormId false string The facebook lead form id associated with this lead.
leads[].tikTok.summary.adgroupId false string The facebook adgroup id associated with this lead.
leads[].tikTok.summary.adId false string The facebook ad id associated with this lead.
leads[].tikTok.summary.createdAtEpochSeconds false long The time this lead was created, as a unix timestamp in seconds.
leads[].tikTok.leadForm false array Values that a person filled out on the lead form.
leads[].tikTok.leadForm[] false object
leads[].tikTok.leadForm[].name false string The name of the facebook lead form field.
leads[].tikTok.leadForm[].values false array An array of the values the user filled out.
leads[].tikTok.leadForm[].values[] false string Each element is a value that the end user selected or entered. In most cases there is only one element.

Audience Manager API

The Audience Manager is a comprehensive audience management system capable of creating, importing, and managing custom audiences for use in marketing campaigns. Evocalize currently supports the creation and management of Meta and Google audiences.

Audience Placeholders are used to associate channel-agnostic audience properties, such as customer data, with multiple audiences spanning multiple channels. Audience Placeholders can be associated with Evocalize-created or partner-provided audiences. Blueprints that support audience targeting are preconfigured to select the best audience per channel from the Audience Placeholder's associated audiences.

Contact your Client Success representative for more information regarding the Audience Manager.

Evocalize-Created Audiences

Audience Placeholders can be associated with audiences created by Evocalize using customer data collected and provided by your organization. Evocalize configures a set of rules for your organization for determining the type of audience(s) to create per channel, the account to create the audience under, and the account(s) to share the audience with.

The creation process for an Audience Placeholder and associated audiences is:

  1. Create an Audience Placeholder using the Create Audience Placeholder API. A successful response should include the newly created Audience Placeholder with a pending status. No audiences are associated with it.
  2. Upload your customer data using the Upload Audience CSV Data API. Upon completion of uploading your customer data, Evocalize will automatically begin creating audiences on behalf of your organization. A successful response should include the Audience Placeholder updated to a processing status.
  3. Audience creation can take up to 24 hours to complete. Channel-specific audiences created by this process will be associated with the Audience Placeholder. Once audience creation is complete, the Audience Placeholder will be updated to a completed status. Moreover, Audience Placeholder and associated audiences can be used in blueprints supporting audience targeting. You can check the status of the Audience Placeholder and associated audiences using the Get Audience Placeholder By ID API.

Partner-Provided Audiences

Audience Placeholders can be associated with active, existing channel-specific audiences provided by your organization. See Add Existing Channel Audience API for more information. Audience Placeholders that are created from a partner-provided audience can immediately be used in blueprints supporting audience targeting.

Create Audience Placeholder

Create Audience Placeholder Request Example

{
  "name": "Audience Placeholder Name",
  "description": "Audience Placeholder Description",
  "tags": [
    "Tag 1"
  ],
  "grants": [
    {
      "grantee": {
        "type": "USER",
        "userId": "exampleUserId"
      },
      "permissions": [
        "READ"
      ]
    }
  ]
}

Create Audience Placeholder Response

{
  "data": {
    "placeholderId": "1234",
    "name": "Audience Placeholder Name",
    "description": "Audience Placeholder Description",
    "status": "pending",
    "tags": [
      "Tag 1"
    ]
  }
}

This endpoint allows you to create an Audience Placeholder which will be used to associate audiences created by Evocalize. Successfully created Audience Placeholders will have a pending status.

You can control who can use audience placeholders by leveraging our standard access control system. READ is currently the only valid permission for audience placeholders. See the Access Control section for more details.

HTTP Request

POST management/v1/audience

Create Audience Placeholder Request Properties

Field Required Type Description
name true String The name of the Audience Placeholder.
description false String The description of the Audience Placeholder. Visible to users in the CMP. Fallbacks to the Audience Placeholder's name if not present.
tags false String List A list of tags to add to the Audience Placeholder.
grants false Grant List A list of grants that define access to the audience placeholder.

Response Codes:

Upload Audience Data CSV

After Evocalize creates audiences on behalf of your organization, these audiences will need to be assigned users using customer data collected by your organization. This customer data can be provided to Evocalize in the form of a CSV and uploaded via this endpoint.

Requirements:

  1. The CSV must contain a header row which is the first row containing the data identifier name of each column.
  2. Every data identifier in the CSV must be hashed as SHA-256 and comply with the requirements listed in the table below. Moreover, there must be at least one data identifier present in your CSV.
  3. In the case of incomplete data for a specific data identifier, omit the header and column data for that data identifier. For example, if you only have a list of email addresses then include only the email address header and column data in your CSV.
  4. The CSV must have at least 300 data identifiers to ensure a minimum of 100 matches.
  5. Although any data identifiers can be present in your CSV, we encourage including a minimum of email or phone. Emails can drive stronger match rates compared to other supported data identifiers.

Audience Data CSV Example (Plain Text)

email,phone,firstname,lastname
emailaddress@example.com,15129876543,test,user

Audience Data CSV Example (SHA-256)

email,phone,firstname,lastname
d42d751294f09be1b195bdea0f5049af7c7da93a99f4c688705ddcacdd16b4c1,88fb2986c52c22fbc4038a49ddd37b3650d0c52806fe520b288672770dc14730,9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08,04f8996da763b7a969b1028ee3007569eaf3a635486ddab211d512c85b9df8fb

Multipart Form Request Example

POST management/v1/audience/{placeholderId}/csv/upload
Content-Type: multipart/form-data; boundary=AUDIENCE-CSV-BOUNDARY
# Authentication Headers

--AUDIENCE-CSV-BOUNDARY
Content-Disposition: form-data; name="file"; filename="hashed_audience_data.csv"
Content-Type: text/csv

email,phone,firstname,lastname
d42d751294f09be1b195bdea0f5049af7c7da93a99f4c688705ddcacdd16b4c1,88fb2986c52c22fbc4038a49ddd37b3650d0c52806fe520b288672770dc14730,9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08,04f8996da763b7a969b1028ee3007569eaf3a635486ddab211d512c85b9df8fb
--AUDIENCE-CSV-BOUNDARY--
Data Identifier Header Description
Email Address email Email must be lowercase, and not have any white space characters.
Phone phone Phone must contain only digits, not have any leading zeros, and be prefixed with the country code.
First Name firstname First name must be lowercase, have no punctuations, and be UTF-8 formatted.
Last Name lastname Last name must be lowercase, have no punctuations, and be UTF-8 formatted.

Upload Audience Data CSV Response

{
  "data": {
    "placeholderId": "1234",
    "name": "Audience Placeholder Name",
    "description": "Audience Placeholder Description",
    "status": "processing",
    "tags": [
      "Tag 1"
    ]
  }
}

This multipart form endpoint can be used to upload your audience data in the form of a CSV. The data must be hashed as SHA-256. When uploading your CSV via this multipart endpoint, specify the CSV under the file key in the multipart form.

HTTP Request (Multipart Form)

POST management/v1/audience/{placeholderId}/csv/upload

URL Params

URL Param Required Type Description
placeholderId true String The ID of the Audience Placeholder.

Upload Audience Data CSV Multipart Form Request

Field Required Type Description
file true CSV A CSV file containing the SHA-256 hashed audience data.

Response Codes:

Add Existing Channel Audience

Add Existing Channel Audience Request Example

{
  "channel": "Facebook",
  "channelAudienceId": "test_facebook_audience_id",
  "name": "Audience Placeholder Name",
  "description": "Audience Placeholder Description",
  "tags": [
    "Tag 1"
  ],
  "grants": [
    {
      "grantee": {
        "type": "USER",
        "userId": "exampleUserId"
      },
      "permissions": [
        "READ"
      ]
    }
  ]
}

Add Existing Channel Audience Response

{
  "data": {
    "placeholderId": "1234",
    "name": "Audience Placeholder Name",
    "description": "Audience Placeholder Description",
    "status": "completed",
    "tags": [
      "Tag 1"
    ],
    "audiences": [
      {
        "channel": "Facebook",
        "channelAudienceId": "test_audience_id",
        "name": "Facebook Audience Name",
        "description": "Facebook Audience Description",
        "type": "custom",
        "potentialSize": "2700000",
        "status": "active"
      }
    ]
  }
}

This endpoint allows importing existing active channel audiences for use in marketing campaigns. Evocalize will verify the audience to be imported is accessible and ready to be used in marketing campaigns. An Audience Placeholder will be created and associated with this existing channel audience Currently, Evocalize supports importing Meta audiences.

You can control access to the imported audience by leveraging our standard access control system. READ is currently the only valid permission for imported audiences. See the Access Control section for more details.

HTTP Request

POST management/v1/audience/provided

Add Existing Channel Audience Request Properties

Field Required Type Description
channel true String The name of the channel the audience was created under.
channelAudienceId true String The ID of the channel-specific audience to be imported.
name false String The name of the Audience Placeholder you are creating. Fallbacks to the channel audience's name if not present
description false String The description of the Audience Placeholder you are creating. Fallbacks to the channel audience's description if not present
tags false String List A list of tags to add to the Audience Placeholder.
grants false Grant List A list of grants that define access to the audience placeholder.

Response Codes:

Valid channel types:

Update Audience Placeholder Permissions

Update Audience Placeholder Permissions Request Example (A group with an additional user)

{
  "grants": [
    {
      "grantee": {
        "type": "GROUP",
        "groupId": "exampleGroupId"
      },
      "permissions": [
        "READ"
      ]
    },
    {
      "grantee": {
        "type": "USER",
        "userId": "exampleUserId"
      },
      "permissions": [
        "READ"
      ]
    }
  ]
}

Update Audience Placeholder Permissions Response

{
  "data": {
    "placeholderId": "1234",
    "name": "Audience Placeholder Name",
    "description": "Audience Placeholder Description",
    "status": "completed",
    "tags": [
      "Tag 1"
    ]
  }
}

You can control who can use audience placeholders by leveraging our standard access control system. This endpoint allows for creating/updating grants on the audience placeholder. Grants are upserted based off of the grantee, so only grants for the given grantees in the request will be touched. Any grantees not included in your request will remain untouched. READ is currently the only valid permission for audience placeholders. You can also provide an empty permissions list in a grant to remove access to the audience placeholder. See the Access Control section for more details.

HTTP Request

POST management/v1/audience/{placeholderId}/grants

Add Audience Placeholder Permissions Request Properties

Field Required Type Description
grants false Grant List A list of grants that define access to the audience placeholder.

Response Codes:

Get Audience Placeholder Permissions

Get Audience Placeholder Permissions Response

{
  "data": {
    "grants": [
      {
        "grantee": {
          "type": "GROUP",
          "groupId": "exampleGroupId"
        },
        "permissions": [
          "READ"
        ]
      },
      {
        "grantee": {
          "type": "USER",
          "userId": "exampleUserId"
        },
        "permissions": [
          "READ"
        ]
      }
    ]
  }
}

This endpoint returns all grants that exist on the placeholder, specified by placeholderId in the request path.

HTTP Request

GET management/v1/audience/{placeholderId}/grants

URL Params

URL Param Required type Description
placeholderId true String The ID of the Audience Placeholder you are wanting to retrieve.

Request Params

Param Required Description
pageToken false The page token (taken from nextPageToken provided in the response) for the page you want to retrieve.

Response Codes:

Response properties

An example is shown to the right. The data property contains a json object holding all the grants you retrieved. See Access Control for full details. READ is the only valid permission for audience access.

Field Nullable Type Description
grants false List of Grant objects A list of the grants retrieved.

Get Audience Placeholders

Returns Audience Placeholders and their associated audiences.

HTTP Request

GET management/v1/audience

Request Params

Param Required Description
pageToken false The page token (taken from nextPageToken provided in the response) for the page you want to retrieve.

Response Codes:

Get Audience Placeholder By ID

Returns the Audience Placeholder and associated audiences.

Get Audience Placeholder By ID Response (Audience Creation Pending, Requires CSV Upload)

{
  "data": {
    "placeholderId": "1234",
    "name": "Audience Placeholder Name",
    "description": "Audience Placeholder Description",
    "status": "pending",
    "tags": [
      "Tag 1"
    ],
    "audiences": []
  }
}

Get Audience Placeholder By ID Response (Audience Creation In Progress)

{
  "data": {
    "placeholderId": "1234",
    "name": "Audience Placeholder Name",
    "description": "Audience Placeholder Description",
    "status": "processing",
    "tags": [
      "Tag 1"
    ],
    "audiences": [
      {
        "channel": "Facebook",
        "channelAudienceId": "test_audience_id",
        "name": "Facebook Audience Name",
        "description": "Facebook Audience Description",
        "type": "custom",
        "potentialSize": null,
        "status": "pending"
      }
    ]
  }
}

Get Audience Placeholder By ID Response (Audience Creation Completed)

{
  "data": {
    "placeholderId": "1234",
    "name": "Audience Placeholder Name",
    "description": "Audience Placeholder Description",
    "status": "completed",
    "tags": [
      "Tag 1"
    ],
    "audiences": [
      {
        "channel": "Facebook",
        "channelAudienceId": "test_audience_id",
        "name": "Facebook Audience Name",
        "description": "Facebook Audience Description",
        "type": "custom",
        "potentialSize": "2700000",
        "status": "active"
      }
    ]
  }
}

HTTP Request

GET management/v1/audience/{placeholderId}

URL Params

URL Param Required type Description
placeholderId true String The ID of the Audience Placeholder you are wanting to retrieve.

Get Audience Placeholder By ID Response Properties

Field Nullable Type Description
placeholderId false String The ID of the Audience Placeholder.
name false String The name of the Audience Placeholder.
description false String The description of the Audience Placeholder.
status false String The status of the Audience Placeholder.
tags false String List A list of tags to add to the Audience Placeholder.
audiences false JSON ARRAY JSON Array of Audience objects. List includes created and active audiences.

Placeholder Statuses:

Audience Response Properties

Field Nullable Type Description
channel false String The name of the channel that audience is created under.
channelAudienceId false String The ID of the channel-specific audience.
name false String The name of the channel-specific audience.
description false String The description of the channel-specific audience.
type false String The type of the channel-specific audience.
potentialSize true String The approximate size of the channel-specific audience. Returns null if audience is being created, -1 for inactive lookalike audiences and < 1000 when size is below 1000.
status false String The status of the channel-specific audience.

Audience Statuses:

Response Codes:

Get Audiences Placeholders For User

Returns a list of Audience Placeholders and associated audiences available to the user.

Get Audience Placeholders For User Response

{
  "data": [
    {
      "placeholderId": "1234",
      "name": "Audience Placeholder Name",
      "description": "Audience Placeholder Description",
      "status": "completed",
      "tags": [
        "Tag 1"
      ],
      "audiences": [
        {
          "channel": "Facebook",
          "channelAudienceId": "test_audience_id",
          "name": "Facebook Audience Name",
          "description": "Facebook Audience Description",
          "type": "custom",
          "potentialSize": "2700000",
          "status": "active"
        }
      ]
    }
  ]
}

HTTP Request

GET management/v1/user/{userId}/audiences

URL Params

URL Param Required type Description
userId true String The ID of the user you are wanting to retrieve audiences for.

Get Audience Placeholders For User Response Properties

Field Nullable Type Description
placeholderId false String The ID of the Audience Placeholder that is user-accessible.
name false String The name of the Audience Placeholder.
description false String The description of the Audience Placeholder.
status false String The status of the Audience Placeholder.
tags false String List A list of tags to add to the Audience Placeholder.
audiences false JSON ARRAY JSON Array of Audience objects. List includes created and active audiences.

Audience Response Properties

Field Nullable Type Description
channel false String The name of the channel that audience is created under.
channelAudienceId false String The ID of the channel-specific audience.
name false String The name of the channel-specific audience.
description false String The description of the channel-specific audience.
type false String The type of the channel-specific audience.
potentialSize true String The approximate size of the channel-specific audience. Returns null if audience is being created, -1 for inactive lookalike audiences and < 1000 when size is below 1000.
status false String The status of the channel-specific audience.

Audience Statuses:

Response Codes:

Digital Asset Management API

The Digital Asset Management API allows for the storage and permissions of various media assets. Media assets are references to media files that are suitable for being used in an advertising creative in at least one of the marking channels supported by the Evocalize platform. Currently, we support image and video assets.

This API can be used to import partner-owned advertising media into their Media Library. You can control who can use media assets by leveraging our standard access control system. READ is currently the only valid permission for media assets. See the Access Control section for more details.

Create Or Update Media

Create Or Update Request Example

{
  "id": "1234",
  "name": "Image Name",
  "type": "image",
  "url": "https://api.example.com/image.png",
  "grants": [
    {
      "grantee": {
        "type": "USER",
        "userId": "exampleUserId"
      },
      "permissions": [
        "READ"
      ]
    }
  ]
}

Create Or Update Response

{
  "data": {
    "id": "1234",
    "name": "Image Name",
    "type": "image",
    "url": "https://api.example.com/image.png"
  }
}

This endpoint allows you to create or update media within your organization.

Users having the ability to read the media will be able to see it in their Media Library via the CMP and create/edit ad campaigns with it. After creation of media, the media type is immutable. On update, the URL and name can change but not the media type.

HTTP Request

POST management/v1/media

Create or Update Media Request Properties

Field Required Type Description
id true String ID of the media you are created/updating. This must be unique per media
name true String Name of the media you are creating/updating.
type true String The media type associated with the URL. Cannot change on updates. Valid types are image, video.
url true String A public URL to the media you would like to import.
grants false Grant List A list of grants that define access to the media asset.

Valid media types:

Response Codes:

Get Media

Get Media Response

{
  "data": {
    "id": "1234",
    "name": "Image Name",
    "type": "image",
    "url": "https://api.example.com/image.png"
  }
}

This endpoint returns the media details, specified by id in the request path.

HTTP Request

GET management/v1/media/{id}

URL Params

URL Param Required type Description
id true String The ID of the media asset you are wanting to retrieve.

Response Codes:

Delete Media

Delete Media response

No Body returned

This allows deleting media from your organization.

Once media is deleted, users will not be able to use it in new ad campaigns. However, active ad campaigns referencing deleted media will continue using the media until completion.

Media created via the Create Or Update Media API can only be deleted via this API. Users owning the media cannot delete the media from their Media Library via the CMP.

HTTP Request

DELETE management/v1/media/{id}

Response Codes:

Update Media Permissions

Update Media Permissions Request Example (A group with an additional user)

{
  "grants": [
    {
      "grantee": {
        "type": "GROUP",
        "groupId": "exampleGroupId"
      },
      "permissions": [
        "READ"
      ]
    },
    {
      "grantee": {
        "type": "USER",
        "userId": "exampleUserId"
      },
      "permissions": [
        "READ"
      ]
    }
  ]
}

Update Media Permissions Response

{
  "data": {
    "id": "1234",
    "name": "Image Name",
    "type": "image",
    "url": "https://api.example.com/image.png"
  }
}

You can control who can use media assets by leveraging our standard access control system. This endpoint allows for creating/updating grants on the media asset. Grants are upserted based off of the grantee, so only grants for the given grantees in the request will be touched. Any grantees not included in your request will remain untouched. READ is currently the only valid permission for media assets. You can also provide an empty permissions list in a grant to remove access to the media asset. See the Access Control section for more details.

HTTP Request

POST management/v1/media/{id}/grants

Add Media Permissions Request Properties

Field Required Type Description
grants false Grant List A list of grants that define access to the media asset.

Response Codes:

Get Media Permissions

Get Media Permissions Response

{
  "data": {
    "grants": [
      {
        "grantee": {
          "type": "GROUP",
          "groupId": "exampleGroupId"
        },
        "permissions": [
          "READ"
        ]
      },
      {
        "grantee": {
          "type": "USER",
          "userId": "exampleUserId"
        },
        "permissions": [
          "READ"
        ]
      }
    ]
  }
}

This endpoint returns all grants that exist on the media, specified by id in the request path.

HTTP Request

GET management/v1/media/{id}/grants

URL Params

URL Param Required type Description
id true String The ID of the media asset you are wanting to retrieve grants for.

Response Codes:

Create Or Update Media Batch

Create Or Update Batch Request

[
  {
    "id": "1234", 
    "name": "Image Name", 
    "type": "image", 
    "url": "https://api.example.com/image.png", 
    "grants": [
      {
        "grantee": {
          "type": "USER", 
          "userId": "exampleUserId"
        }, 
        "permissions": [
          "READ"
        ]
      }
    ]
  },
  // ...
]

Create Or Update Batch Response

{
  "data": {
    "reportId": "HG3SrEndQch8dAZbjwBV"
  }
}

This endpoint allows you to pass a JSON Array of User Request objects for creation or updating. Batches are limited to 1000 items at a time. The creation option is asynchronous - rather than returning the newly created items, you will receive a report_id which can be used to track status of the requests as they are processed in our system. Reports are stored for 30 days.

The JSON objects passed in the array are the same as the ones listed in Create Or Update Media endpoint.

HTTP Request

POST management/v1/medias

Response Codes:

Errors

We return the appropriate HTTP Status code when we return an error. Additionally we do our best to provide a human readable error message to help you figure out what went wrong.

Error Code HTTP Status Code Meaning
EV_BAD_REQUEST_INVALID_FIELDS 400 Request is missing required fields or has failed validation check.
EV_BAD_REQUEST_INVALID_USER_IDENTITY 400 Request contains an invalid user or group, e.g., user does not exist.
EV_BAD_REQUEST_TOO_MANY_ITEMS 400 Batch request contains too many items.
EV_BAD_REQUEST_MALFORMED 400 Malformed request, e.g. a type mismatch.
EV_BAD_REQUEST_DUPLICATE 400 An object with a different id already exists.
EV_BAD_REQUEST_INVALID_BUDGET 400 The requested budget change is invalid.
EV_BAD_REQUEST_INVALID_SCHEDULE 400 The requested schedule change is invalid.
EV_BAD_REQUEST_INVALID_VARIABLE_VALUE 400 The requested variable value change is invalid.
EV_OBJECT_NOT_EDITABLE_TEMPORARILY 400 The object cannot be edited at the moment. Please try again later.
EV_OBJECT_NOT_FOUND 404 Unable to locate requested resource.
EV_UNAUTHORIZED_INVALID_KEY 401 Provided Client Key Id is invalid.
EV_UNAUTHORIZED_MISSING_HEADERS 401 Request is missing one of the required headers.
EV_UNAUTHORIZED_INVALID_SIGNATURE 401 Signature provided in X-Evocalize-Signature is not valid.
EV_UNAUTHORIZED_INVALID_SECRET 401 Secret provided in X-Evocalize-Client-Key is not valid.
EV_UNAUTHORIZED_EXPIRED_REQUEST 401 Request timestamp is over 1 minute old.
EV_INTERNAL_SERVER_ERROR 500 We had a problem with our server. Try again later.

Architecture Deep Linking

Content

The following information explains how to generate a deep link to take a user to view all of their content under a specific architecture.

Base URL

/#/architecture/<ARCHITECTURE_ID>/content

Query Parameters

Content Filter Example - adding an automatic filter on the status attribute where the value contains "Sold"

contentFilter=%7B%22status%22%3A%20%7B%22contains%22%3A%20%22Sold%22%7D%7D

The raw value from the example above is

{
  "status": {
    "contains": "Sold"
  }
}

All query parameters must be properly encoded URI components. For further information on this, please see documentation here

Query Param Required type Description
contentFilter false Encoded JSON JSON enabling filtering of content
sideNav false String "closed" or "open" to control whether or not the left nav is displayed.

Currently Running Programs

The link below is where you should send users to view all the purchases they have made for a specific architecture.

Base URL

/#/architecture/<ARCHITECTURE_ID>/programs

Query Parameters

Query Param Required type Description
sideNav false String "closed" or "open" to control whether or not the left nav is displayed.

Program Creation/Purchase Base

This URL will take a user to the order process without a Blueprint or any items selected (they will be prompted to select both in the UI):

Base PATH

/#/architecture/<ARCHITECTURE_ID>/programCreate

Query Parameters

Send a user to the place order page with a specific blueprint selected

redirectUser(
    "https://your-white-label-domain.com/#/architecture/<ARCHITECTURE_ID>/programCreate?productIds=<BLUEPRINT_ID>"
);

Send a user to the place order page with a blueprint selected and one of their items selected

redirectUser(
    "https://your-white-label-domain.com/#/architecture/<ARCHITECTURE_ID>/programCreate?productIds=<BLUEPRINT_ID>&contentIds=<CONTENT_ID_1>"
);

Send a user to the place order page with a blueprint selected and pre-selected filters in the content selector modal

redirectUser(
    "https://your-white-label-domain.com/#/architecture/<ARCHITECTURE_ID>/programCreate?productIds=<BLUEPRINT_ID>&contentFilter=<ENCODED_JSON_CONTENT_FILTER>"
);

The following parameters can be used on their own or together to pre-select form field options for a user. These can help reduce steps for users to place an order by pre-selecting things like content or a Blueprint. Users can still change these values once the page has loaded.

Query Param Required type Description
productIds false Int A single blueprint ID. Pre-selects the blueprint for program creation.
contentIds false Int Array Comma-separated IDs. Pre-selects content to be used for the program.
contentFilter false Encoded JSON JSON enabling filtering of content. Pre-filters content shown in the content selector modal.
sideNav false String "closed" or "open" to control whether or not the left nav is displayed.
step false String values: (spend, summary) Attempts to skip to a specific step of the program creation. Will not skip a step if there is a validation error.
promoCodes false String pre populates the promo code component with the supplied promo code. This is a comma separated list, but only one promo is supported

Automated Program Creation

This URL will take a user to the automated program creation screen.

Base URL

/#/architecture/<ARCHITECTURE_ID>/automatedProgramCreate

Query Parameters

Filter JSON example

[
  {
    "column": "agent_name",
    "rules": [
      {
        "operator": "eq",
        "value": "Jim FakeName"
      },
      {
        "operator": "eq",
        "value": "Jane FakeName"
      }
    ]
  },
  {
    "column": "price",
    "rules": [
      {
        "operator": "range",
        "value": {
          "gt": 1000000,
          "lt": 2000000
        }
      }
    ]
  }
]

Optionally remove whitespace and line breaks. As long as all the white space is url encoded this step is not required, but it results in a shorter url. Take care not to remove space in string values e.g. "New York" vs "NewYork"

[{"column":"agent_name","rules":[{"operator":"eq","value":"Jim FakeName"},{"operator":"eq","value":"Jane FakeName"}]},{"column":"price","rules":[{"operator":"range","value":{"gt":1000000,"lt":2000000}}]}]

Convert to url parameter

filters=%5B%7B%22column%22%3A%22agent_name%22%2C%22rules%22%3A%5B%7B%22operator%22%3A%22eq%22%2C%22value%22%3A%22Jim%20FakeName%22%7D%2C%7B%22operator%22%3A%22eq%22%2C%22value%22%3A%22Jane%20FakeName%22%7D%5D%7D%2C%7B%22column%22%3A%22price%22%2C%22rules%22%3A%5B%7B%22operator%22%3A%22range%22%2C%22value%22%3A%7B%22gt%22%3A1000000%2C%22lt%22%3A2000000%7D%7D%5D%7D%5D
Query Param Required type Description
sideNav false String "closed" or "open" to control whether or not the left nav is displayed.
filters false encoded JSON A json array of filters with the column you are filtering, along with an array of rules with operator and value.
showWizard false boolean Whether or not the automated programs wizard should be displayed. Defaults to true if not provided.

Filters

As explained in the query param table above, filters is a json array of filters with the column you are filtering, along with an array of rules with operator and value: