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.

Webhooks

Webhooks allow you to receive real-time HTTP notifications when events occur in your TruCentive account. Instead of polling the API to check for updates, webhooks push data to your server as events happen.

Overview

When an event occurs (such as an envelope being delivered, viewed, or opened), TruCentive sends an HTTP POST request to your configured webhook URL with details about the event. This enables you to:

Update your systems in real-time when recipients interact with envelopes
Trigger automated workflows based on envelope events
Maintain synchronized records without polling the API

Webhook Events

TruCentive can send webhooks for the following envelope state change events:

Event	Description
envelope.pending	An envelope has been created and is pending processing
envelope.approval_needed	An envelope requires approval before delivery
envelope.approved	An envelope has been approved for delivery
envelope.pending_delivery	An envelope is queued for delivery
envelope.delivered	An envelope has been successfully delivered to the recipient
envelope.viewed	A recipient has viewed their envelope
envelope.opened	A recipient has opened (redeemed) their envelope
envelope.expired	An envelope has expired without being redeemed
envelope.rejected	An envelope has been rejected
envelope.revoked	An envelope has been revoked

Webhook Payload

Example webhook payload for an envelope.delivered event:

{
  "event": "envelope.delivered",
  "timestamp": "2024-01-15T14:30:00.123Z",
  "webhook_id": "whk-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "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": "2024-01-15T14:30:00.000Z",
    "opened_at": null,
    "viewed_at": null,
    "expires_at": "2024-02-15T23:59:59.999Z",
    "test_mode": false,
    "custom_fields": {
      "custom_color": "periwinkle"
    }
  }
}

Example webhook payload for an envelope.viewed event:

{
  "event": "envelope.viewed",
  "timestamp": "2024-01-16T10:15:00.456Z",
  "webhook_id": "whk-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "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": "2024-01-15T14:30:00.000Z",
    "opened_at": null,
    "viewed_at": "2024-01-16T10:15:00.000Z",
    "expires_at": "2024-02-15T23:59:59.999Z",
    "test_mode": false,
    "custom_fields": {
      "custom_color": "periwinkle"
    }
  }
}

Example webhook payload for an envelope.opened event with redemption_url:

{
  "event": "envelope.opened",
  "timestamp": "2024-01-16T10:20:00.789Z",
  "webhook_id": "whk-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "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": "opened",
    "delivered_at": "2024-01-15T14:30:00.000Z",
    "opened_at": "2024-01-16T10:20:00.000Z",
    "viewed_at": "2024-01-16T10:15:00.000Z",
    "expires_at": "2024-02-15T23:59:59.999Z",
    "test_mode": false,
    "custom_fields": {
      "custom_color": "periwinkle"
    },
    "redemption_url": "https://example.com/redeem/abc123"
  }
}

All webhook payloads include the following fields:

Field	Description
event	The type of event that triggered the webhook (e.g., `envelope.delivered`)
timestamp	ISO 8601 timestamp with millisecond precision of when the event occurred
webhook_id	The unique identifier of the webhook configuration that triggered this delivery
data	The envelope object with full details

Data Object Fields

Field	Description
id	The envelope identifier
uuid	The envelope UUID (same as id)
addresses	Array of delivery addresses with uuid, format, and delivery_address
project	Object containing the project uuid and name
state	Current state of the envelope
delivered_at	Timestamp when the envelope was delivered (null if not yet delivered)
viewed_at	Timestamp when the envelope was viewed (null if not yet viewed)
opened_at	Timestamp when the envelope was opened/redeemed (null if not yet opened)
expires_at	Timestamp when the envelope expires
test_mode	Boolean indicating if this is a test envelope
custom_fields	Object containing custom field values (only included if your account has custom fields enabled)
redemption_url	External redemption URL (only included for opened envelopes when the webhook has redemption_url enabled and the selected incentive has an external URL)

Verifying Webhook Signatures

Example signature verification in Ruby:

# The signature is sent in the TruCentive-Signature header
# Format: sha256=<hexdigest>

# Ruby example:
require 'openssl'

received_signature = request.headers['TruCentive-Signature']
payload_body = request.body.read

expected_signature = 'sha256=' + OpenSSL::HMAC.hexdigest(
  'SHA256',
  webhook_signing_secret,
  payload_body
)

if Rack::Utils.secure_compare(expected_signature, received_signature)
  # Signature is valid
end

Example signature verification in Node.js:

# Node.js example:
const crypto = require('crypto');

const receivedSignature = req.headers['trucentive-signature'];
const payloadBody = JSON.stringify(req.body);

const expectedSignature = 'sha256=' + crypto
  .createHmac('sha256', webhookSigningSecret)
  .update(payloadBody)
  .digest('hex');

if (crypto.timingSafeEqual(
  Buffer.from(expectedSignature),
  Buffer.from(receivedSignature)
)) {
  // Signature is valid
}

Example signature verification in Python:

# Python example:
import hmac
import hashlib

received_signature = request.headers.get('TruCentive-Signature')
payload_body = request.get_data(as_text=True)

expected_signature = 'sha256=' + hmac.new(
    webhook_signing_secret.encode(),
    payload_body.encode(),
    hashlib.sha256
).hexdigest()

if hmac.compare_digest(expected_signature, received_signature):
    # Signature is valid

To verify that a webhook request is authentic and originated from TruCentive, each webhook request includes a signature in the TruCentive-Signature header.

The signature format is sha256=<hexdigest>, where the hexdigest is computed as an HMAC-SHA256 hash of the raw JSON request body using your webhook signing secret as the key.

Verification Steps

Extract the signature from the TruCentive-Signature header
Compute the HMAC-SHA256 hash of the raw request body using your webhook signing secret
Prepend sha256= to the computed hexdigest
Compare the computed signature to the received signature using a constant-time comparison function
Only process the webhook if the signatures match

Your webhook signing secret can be found in your account settings alongside your webhook configuration. You can regenerate the signing secret at any time if it becomes compromised.

HTTP Request Details

TruCentive webhook requests include the following headers:

Header	Value
Content-Type	application/json
TruCentive-Signature	sha256=<hexdigest>
User-Agent	TruCentive-Webhooks/1.0

Responding to Webhooks

Your webhook endpoint should return a 2xx HTTP status code to acknowledge receipt of the webhook. Any other status code will be treated as a failure.

Return a 200 OK response as quickly as possible. The webhook request has a 5-second timeout. Perform any time-consuming processing asynchronously after acknowledging the webhook.

Best Practices

Idempotency

Your webhook handler should be idempotent, meaning it can safely receive the same webhook multiple times without causing duplicate side effects. Store the envelope uuid and event type to detect and ignore duplicate webhooks.

Security

Always verify the webhook signature before processing
Use HTTPS for your webhook endpoint (required)
Keep your webhook signing secret secure and regenerate it if compromised
Validate that the envelope UUID in the webhook corresponds to a known envelope in your system

Performance

Respond to webhooks quickly (within 5 seconds)
Process webhook data asynchronously if your handler requires time-consuming operations
Use a queue to handle high volumes of webhooks

Error Handling

Log all received webhooks for debugging purposes
Monitor your webhook endpoint for failures
Set up alerts for webhook delivery failures

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.