Introduction

Welcome to the Evocalize management API. This API is designed for end users of the Evocalize Developer Tools platform.

Request And Response Info

Headers

Example Headers

x-evocalize-client-key-id: a5646c38-fc29-11e9-8f0b-362b9e155667
x-evocalize-timestamp: 1604094273
x-evocalize-signature: 690a0ac5a5a219bb4a773f5bc116a32553be4e8380845d854f07b5e8471bc954
Content-Type: application/json

Header info

Signing Requests:

Request signing example

// Concatenate all the parts
val toValidate = 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(myClientSecret)
  .toString()

val expectedSignature = Hashing.sha256().hashString(toValidate, Charsets.UTF_8)

// expectedSignature will match request.headers["X-Evocalize-Signature"]

For security and identity purposes, we require all partners to sign all API requests. The methodology is straight forward. Join the following values with a new line character between each item

• UrlPath (including path params if present)
• Any POST data (leave this out if you are not POSTing a body)
• Value of the timestamp used in the X-Evocalize-Timestamp Header
• Client Secret (this will be provided by Evocalize)

Response Format

JSON Response Schema

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

Example Success Response:

{
  "data": {
    "<Request Specifc JSON Response>"
  }
}

Example Error Response:

{
  "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 transmit null values. The most common responses will look like the examples provided.

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

Response Codes:

• 200 OK status code on sucess
• 404 NOT FOUND when it can't locate the user.

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": "longtokenstringgoeshere", // only present when there are more pages
  "previousPageToken": "differenttokenstringgoeshere" // only present when 
}

Returns all users. This is a paginated response - returning 100 results per page.

HTTP Request

GET management/v1/users

Request Params

Response Codes:

• 200 OK - NOTE: will return an empty array and this status code if there are no users present.

Create Or Update User

Create Request Example

{
    "id": "String", 
    "email": "String", 
    "name": "String",
    "groups": [
      {
        "userId": "String", 
          "groupId": "String",
          "role": "String"
      },
    // ... 
    ]
}

Update Request Example

{
    "id": "String",
    "email": "user@example.com",
    "name": "Test User",
    "replaceGroups": false,
    "groups": [
        {
            "userId": "56468",
            "groupId": "8675309",
            "role": "group_admin"
        }
    ]
  // ...
}

Create and Update Repsonse

{
    "id":"test_user_id", 
    "email":"user@example.com", 
    "name":"Test User", 
    "groups": [
        {
            "userId": "56468", 
            "groupId": "8675309",
            "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 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

Update User Request Properties

User Group Association Properties

Valid group roles:

• group_user
• group_admin

Response Codes:

• 201 CREATED - Returning the newly created / updated user.
• 400 BAD REQUEST - When the request is malformed or you attempt to associate to a non existant group.

Create Or Update User Batch

Batch Create Request

[
  {
    "id": "String", 
    "email": "String", 
    "name": "String", 
    "groups": [
      {
      "userId": "String", 
      "groupId": "String",
      "role": "String"
      },
        // ... 
    ]
  },
  // ...
]

Batch Update Request

[
  {
    "id":"String",
    "email":"user@example.com",
    "name":"Test User",
    "replaceGroups": false,
    "groups": [
      {
        "userId": "56468", 
        "groupId": "8675309",
        "role": "group_admin"
      },
      // ... 
    ]
  },
  // ...
]

Create and Update Batch Repsonse

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

Endpoint that 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:

• 202 ACCEPTED - List has been received and submitted for processing.
• 400 BAD REQUEST - Malformed request.

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:

• 202 ACCEPTED

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": "longtokenstringgoeshere",
  "previousPageToken": "differenttokenstringgoeshere"
}

Returns all groups. This is a paginated response - returning 100 results per page.

HTTP Request

GET management/v1/groups

Request Params

Response Codes:

• 200 OK NOTE: will return an empty array and this status code if there are no groups present.

Create Or Update Group

Group Create/Update Request

{
 "id": "String", 
 "name": "String",  
}

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

Response Codes:

• 201 CREATED

Create Or Update Group Batch

Group Create Request

[
    {
     "id": "String", 
     "name": "String",  
    },
  // ...
]

Group Create 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:

• 202 ACCEPTED - List has been received and submitted for processing.
• 400 BAD REQUEST - Malformed request.

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.

HTTP Request

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

URL Params

Response Codes:

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

Errors

We always attempt to 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 unblock you.