Introduction

Welcome to the TruCentive API! You can use our API to access TruCentive API endpoints. Note that the API endpoint for your account may differ from those shown here.

Authentication

There are two forms of authorization available: An API key, or OAuth. For using the API directly we recommend the API Key. We also provide Zapier integration which works via OAuth and can enable integration of the API without any coding.

Example authorization using an API key:

curl --header "Authorization: API_KEY" https://app.trucentive.com/api/v1

Make sure to replace API_KEY with your API key.

You can create an API key on your 'Account' -> 'API Access' page on the Trucentive Website.

TruCentive expects for the API key to be included in all API requests to the server in an 'Authorization' header like this:

Authorization: API_KEY

Alternatively, you can provide the API key as a URL parameter (we recommend using the Authorization Header method as it is more secure):

https://app.trucentive.com/api/v1?api_key=API_KEY

You must replace API_KEY with your personal API key.

Account

Get Account Information

curl https://app.trucentive.com/api/v1/me?api_key=API_KEY

The above command returns JSON structured like this:

{
  "id": "user-e6a53849-fb46-4abd-9f43-c88c58705a9d",
  "uuid": "user-e6a53849-fb46-4abd-9f43-c88c58705a9d",
  "email": "john.smith@test.com",
  "name": "John Smith",
}

This endpoint retrieves information about the currently authenticated account.

HTTP Request

GET https://app.trucentive.com/api/v1/me

Query Parameters

None

Projects

Get Projects

GET https://app.trucentive.com/api/v1/projects

curl https://app.trucentive.com/api/v1/projects?api_key=API_KEY

The above command returns JSON structured like this:

[
  {
  "id": "project-e6a53849-fb46-4abd-9f43-c88c58705a9d",
  "uuid": "project-e6a53849-fb46-4abd-9f43-c88c58705a9d",
  "name": "Test Project",
  "description": "This is a test project",
  "account_uuid": "account-36d7d9e9-1ff9-4fd4-ad6f-991f0526f52c",
  "starts_at": "2019-11-31T19:21:21.322Z",
  "expires_at": null,
  "created_at": "2019-11-25T21:44:54.911Z",
  "min_instrument_value": 5.0,
  "max_instrument_value": 30.25,
  "test_mode": false,
  "custom_fields":["custom_color"]
 }
]

This API endpoint returns a list of projects that the currently authenticated account has access to.

Query Parameters

None

Get Project Instruments

GET https://app.trucentive.com/api/v1/project/instruments?project_uuid=UUID

curl https://app.trucentive.com/api/v1/project/instruments?project_uuid=UUID&api_key=API_KEY

The above command returns JSON structured like this:

[
  {
  "id": "inst-d3c774ac-3f48-4dfc-bf76-af79d2e3433e",
  "uuid": "inst-d3c774ac-3f48-4dfc-bf76-af79d2e3433e",
  "name": "Target Gift Card",
  "description": "Target Gift Card in any value"
 }
]

This API endpoint returns a list of available 'instruments' for project. Instruments are the types of incentives that can be sent to users for this project (an Amazon gift card, or a physical product would be an instrument).

Query Parameters

Parameter	Default	Description
project_uuid	true	The UUID of the project to retrieve available instruments for

Envelopes

Send An Envelope

POST https://app.trucentive.com/api/v1/envelope/deliver

curl -X POST https://app.trucentive.com/api/v1/project/instruments?api_key=API_KEY
  -d project_uuid=project-e6a53849-fb46-4abd-9f43-c88c58705a9d \
  -d amount=5.00 \
  -d address=john.smith@test.com \
  -d instrument_uuid=inst-d3c774ac-3f48-4dfc-bf76-af79d2e3433e \
  -d first_name=John \
  -d last_name=Smith \
  -d "custom_fields[custom_color]=periwinkle"

The above command returns JSON structured like this with information about the envelope queued for delivery.

  {
    "message":"Envelope queued for delivery",
    "envelope":
      {
        "id":"CDVLBYYIOPHLJVWYEF",
        "uuid":"CDVLBYYIOPHLJVWYEF",
        "addresses": [
          {
            "uuid":"addr-9d2db7c4-0351-47c7-9d43-330641f4be3f",
            "format":"mailto",
            "delivery_address":"john.smith@test.com"
          },
        ],
        "project": {
          "uuid":"project-e6a53849-fb46-4abd-9f43-c88c58705a9d",
          "name":"Test Project"
        },
        "state":"delivered",
        "delivered_at": null,
        "opened_at": null,
        "viewed_at": null,
        "expires_at":"2019-12-09T23:59:59.999Z",
        "test_mode":false,
        "custom_fields":{"custom_color":"periwinkle"}
      }
  }

Possible errors

Outside of the standard API error messages in the errors section below there are several error messages that can be returned in the 'error' field of the json error message with the status code 400.

If an error occurs it will be returned like this:

{
  "error": "Exceeds available funds",
  "status": 400
}

Invalid value - If the card is requested for a value that is not valid for that instrument.
No cards available for that amount - If a card is requested for a value and is not available in that value.
Exceeds available funds - If the allocated funds for this project or card are exceeded.
Invalid delivery address - If the delivery email or SMS addres is not valid.

Query Parameters

Parameter	Default	Description
project_uuid	true	UUID of the project
amount	true	Amount in dollars and cents to gift, ex: 5.50. If the project has a fixed value this parameter will be ignored.
address	true	The email address or phone number to send to
instrument_uuid	true	The instrument (type of reward) to send
first_name	false	The first name of the person the envelope is being sent to
last_name	false	The last name of the person the envelope is being sent to
batch_allowed	false	Boolean - When batch_allowed is true, trucentive will not deliver the email. You can fetch the URL from the SHOW Envelope endpoint.

Custom Fields

Custom Fields may be included in the envelope delivery request. The custom fields must be defined beforehand in your account. Format the data like this:

custom_fields: { "custom_color": "periwinkle", "custom_size": "large" }

Get Envelope Details

GET https://app.trucentive.com/api/v1/envelope

The above command returns JSON structured like this:

  {
    "id":"CDVLBYYIOPHLJVWYEF",
    "uuid":"CDVLBYYIOPHLJVWYEF",
    "addresses": [
      {
        "uuid":"addr-9d2db7c4-0351-47c7-9d43-330641f4be3f",
        "format":"mailto",
        "delivery_address":"john.smith@test.com"
      },
      {
        "uuid":"addr-2e947b94-c676-4696-b184-01994a38b07f",
        "format":"sms",
        "delivery_address":"261-123-1231"
      }
    ],
    "project": {
      "uuid":"project-2690d664-5199-4fe0-a37c-6f3cc339d882",
      "name":"Test Project"
    },
    "state":"approved",
    "delivered_at":"2019-12-09T23:59:59.999Z",
    "opened_at":null,
    "viewed_at":"2019-12-09T23:59:59.999Z",
    "expires_at":"2019-12-09T23:59:59.999Z",
    "test_mode":false
  }

This API endpoint returns details of an envelope.

Query Parameters

Parameter	Default	Description
envelope_uuid	false	Required - The ID of the envelope to fetch
show_url	false	Boolean - if show_url is "true" the response will include a url attribute that can redeem the envelope
redemption_url	false	Boolean - if redemption_url is "true" AND envelope is open AND selected incentive has an external redemption URL the response will include a redemption_url attribute for the selected incentive

Get Viewed Envelopes

GET https://app.trucentive.com/api/v1/envelopes/viewed

The above command returns JSON structured like this:

[
  {
    "id":"CDVLBYYIOPHLJVWYEF",
    "uuid":"CDVLBYYIOPHLJVWYEF",
    "addresses": [
      {
        "uuid":"addr-9d2db7c4-0351-47c7-9d43-330641f4be3f",
        "format":"mailto",
        "delivery_address":"john.smith@test.com"
      },
      {
        "uuid":"addr-2e947b94-c676-4696-b184-01994a38b07f",
        "format":"sms",
        "delivery_address":"261-123-1231"
      }
    ],
    "project": {
      "uuid":"project-2690d664-5199-4fe0-a37c-6f3cc339d882",
      "name":"Test Project"
    },
    "state":"approved",
    "delivered_at":"2019-12-09T23:59:59.999Z",
    "opened_at":null,
    "viewed_at":"2019-12-09T23:59:59.999Z",
    "expires_at":"2019-12-09T23:59:59.999Z",
    "test_mode":false
  }
]

This API endpoint returns a list of envelopes viewed in the last hour (by default, but can be configured using a query parameter) for projects that the currently authorized account has accss to.

Query Parameters

Parameter	Default	Description
since	false	The number of seconds to look back, see API description above.

Get Opened Envelopes

GET https://app.trucentive.com/api/v1/envelopes/opened

The above command returns JSON structured like this:

[
  {
    "id":"CDVLBYYIOPHLJVWYEF",
    "uuid":"CDVLBYYIOPHLJVWYEF",
    "addresses": [
      {
        "uuid":"addr-9d2db7c4-0351-47c7-9d43-330641f4be3f",
        "format":"mailto",
        "delivery_address":"john.smith@test.com"
      },
      {
        "uuid":"addr-2e947b94-c676-4696-b184-01994a38b07f",
        "format":"sms",
        "delivery_address":"261-123-1231"
      }
    ],
    "project": {
      "uuid":"project-2690d664-5199-4fe0-a37c-6f3cc339d882",
      "name":"Test Project"
    },
    "state":"approved",
    "delivered_at":"2019-12-09T23:59:59.999Z",
    "opened_at":null,
    "viewed_at":"2019-12-09T23:59:59.999Z",
    "expires_at":"2019-12-09T23:59:59.999Z",
    "test_mode":false
  }
]

Open An Envelope

POST https://app.trucentive.com/api/v1/envelopes/:envelope_id/open

curl -X POST https://app.trucentive.com/api/v1/envelopes/CDVLBYYIOPHLJVWYEF/open?api_key=API_KEY

The above command returns JSON structured like this with information about the envelope queued for opening.

  {
    "message":"Envelope queued for opening",
    "envelope":
      {
        "id":"CDVLBYYIOPHLJVWYEF",
        "uuid":"CDVLBYYIOPHLJVWYEF",
        "addresses": [
          {
            "uuid":"addr-9d2db7c4-0351-47c7-9d43-330641f4be3f",
            "format":"mailto",
            "delivery_address":"john.smith@test.com"
          },
        ],
        "project": {
          "uuid":"project-e6a53849-fb46-4abd-9f43-c88c58705a9d",
          "name":"Test Project"
        },
        "state":"delivered",
        "delivered_at": "2019-11-09T23:59:59.999Z",
        "opened_at": null,
        "viewed_at": null,
        "expires_at":"2019-12-09T23:59:59.999Z",
        "test_mode":false,
        "custom_fields":{"custom_color":"periwinkle"}
      }
  }

This API endpoint will queue an envelope for opening. Envelope opening happens asynchronously. The Envelope details endpoint can be used to monitor the status of the envelope if you need to see the result of this operation. Failures and errors may occur during opening even when this API call is successful. It is safe to retry opening an envelope.

Possible errors

Outside of the standard API error messages in the errors section below there are several error messages that can be returned in the 'error' field of the json error message with the status code 400.

If an error occurs it will be returned like this:

{
  "error": "Cannot open envelope.",
  "status": 400,
  "details": {
    "full_error_messages": "Envelope cannot be opened because the envelope is locked"
  }
}

Locked - If the envelope was a gated delivery it is currently not supported to open by the API.
Cannot choose incentive - The incentive cannot be chosen for the envelope. For example, the envelope has expired or there are multiple incentives to choose.

Query Parameters

Parameter	Default	Description
envelope_id	false	ID of the envelope to open

Sessions

Get Account Sessions

GET https://app.trucentive.com/api/v1/sessions

curl --header "Authorization: API_KEY" -i https://app.trucentive.com/api/v1/sessions

The above command returns JSON structured like this:

[
  {
    "ip": "10.10.10.10",
    "email": "sergey@google.com"
  },
  {
    "ip": "10.10.10.10",
    "email": "larry@google.com"
 }
]

This API endpoint returns a paginated list of sessions sorted by the order they were created with the most recent first. Sessions represent successful logins by users of your account.

Query Parameters

Parameter	Default	Description
page	true	The page of session results with 1 as the first page.

Errors

All errors will have the following JSON attached containing more detail about the error message.

{
  "error": "More detail about the error",
  "status": 400
}

The TruCentive API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid, please see the json error.
403	Access Denied -- Your API key is wrong or your OAuth account is not authorized.
404	Not Found -- The specified API or resource could not be found.
406	Not Acceptable -- You requested a format that isn't valid.
429	Too Many Requests -- You've submitted too many API requests in too short a time, try again later.
500	Internal Server Error -- We had a problem processing your request, please try again later or contact support.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.