NAV Navbar
shell

Introduction

You can use OnVoard's API to access various endpoints, such as retrieving contacts or add contact activities. Some key use cases supported by OnVoard's API includes:

# Api calls must be made with token header
curl 'https://api.onvoard.com/v2/reviews' \
-H 'X-API-Key: {API_KEY}'

OnVoard currently use api key for authentication. Go to api details page to get your api key. Add X-API-Key: {API_KEY} header to your api request for authentication.

Pagination

# Return up to 50 records for page 3.
https://api.onvoard.com/v2/reviews?page=3&page_size=50

The default page size for paginated queries is 10. You can increase the page size to return up to 100 records by specifying the page_size parameter in your GET request. You can traverse to specific page with the page parameter. Index for page starts from 1.

Errors

Any request that did not succeed will return a 4xx or 5xx error. 4xx range errors means that there's a problem with the request, such as missing parameter. 5xx range means that something went wrong on our end, such as server failure.

Activities/Events Integration (Tutorial)

For third party platforms, you can pust contact events from your platform to OnVoard by adding custom contact activities. Synced activities can be used to segment contacts or trigger workflows. In this walkthrough, we'll show an example on how we integrate Stripe's charge created event.

1) Create Resource

Example Request

curl https://api.onvoard.com/v2/resources \
-X POST \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "key": "stripe_charge_created",
  "name": "Stripe Charge Created",
  "kind": "ACTIVITY",
  "icon_type": "UPLOADED",
  "icon_url": "https://pbs.twimg.com/profile_images/1422297335531376654/f0wnwzb-_200x200.jpg"
}'

Example Response

{
  "id": "resrc_26tn6i20ehdo49m",
  "namespace": "custom",
  "key": "stripe_charge_created",
  "accessor": "custom.stripe_charge_created",
  "name": "Stripe Charge Created",
  "helper_text": "",
  "type": "CUSTOM",
  "kind": "ACTIVITY",
  "icon_type": "UPLOADED",
  "icon_class": "",
  "icon_media": {
    "id": "file_74g6fj02jtsgqgm",
    "file_url": "https://storage.googleapis.com/onvoard/upload/resource/icon-media/62f2a39cd332de7f95f672.jpeg",
    "created_datetime": "2021-12-31T15:09:43.769901Z",
    "height": 200,
    "width": 200
  }
}

First, we'll create a resource for stripe_charge_created.

2) Create Resource Property Types

Example Request

```shell
curl https://api.onvoard.com/v2/resource-property-types \
-X POST \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "resource": "resrc_26tn6i20ehdo49m",
  "key": "amount",
  "label": "Amount",
  "value_type": "NUMBER",
  "helper_text": "Amount charged in local currency.",
}'

Example Response

{
  "id": "2cp9xk798bxtnub",
  "key": "amount",
  "label": "Amount",
  "helper_text": "Amount charged in local currency.",
  "field_type": "",
  "value_type": "NUMBER",
  "resource_id": "resrc_26tn6i20ehdo49m",
  "resource_accessor": "custom.stripe_charge_created"
}

When you create a resource with ACTIVITY kind, OnVoard will automatically add the following property types (proptypes) for created resource.

In many cases, you would want to add more properties. For that, you need to create proptype for each additional property that you wish to use.

In this example, we'll create a proptype for amount to denotate amount charged.

3) Create Activity Type

Example Request

curl https://api.onvoard.com/v2/contact-activity-types \
-X POST \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "resource": "resrc_26tn6i20ehdo49m",
  "descriptor_template": "Charged amount: {{ amount }}"
}'

Example Response

{
  "id": "catype_fm2cdnac4wcxc8p",
  "resource": {
    "id": "resrc_26tn6i20ehdo49m",
    "namespace": "custom",
    "key": "stripe_charge_created",
    "accessor": "custom.stripe_charge_created",
    "name": "Stripe Charge Created",
    "helper_text": "",
    "type": "CUSTOM",
    "kind": "ACTIVITY",
    "icon_type": "UPLOADED",
    "icon_class": "",
    "icon_media": {
      "id": "file_74g6fj02jtsgqgm",
      "file_url": "https://storage.googleapis.com/onvoard/upload/resource/icon-media/62f2a39cd332de7f95f672.jpeg",
      "created_datetime": "2021-12-31T15:09:43.769901Z",
      "height": 200,
      "width": 200
    }
  },
  "descriptor_template": "Charged amount: {{ amount }}"
}

Now that resource is ready, we'll create activity type that will be linked with resource.

4) Add Activities

Example Request

curl https://api.onvoard.com/v2/contact-activity-types \
-X POST \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "contact_email": "jane@example.com",
  "type": "custom.stripe_charge_created",
  "record_data": {
    "amount": 79
  }
}'

Example Response

{
  "id": "ctact_xlxpbshpx56abs41adwp",
  "contact": {
    "id": "ct_qauejq13aixtowf",
    "email": "jane@example.com"
  },
  "type": "custom.stripe_charge_created",
  "datetime": "2021-12-31T20:25:54Z",
  "record_data": {
    "amount": 79.0,
    "contact_id": "ct_qauejq13aixtowf",
    "activity_id": "ctact_xlxpbshpx56abs41adwp",
    "contact_email": "jane@example.com",
    "activity_datetime": 1640982354
  }
}

Finally, we can add contact activities. We'll specify amount to record data. Record data can be used to evaluate conditions for segments and workflows logic. You can even use these variables to render email content.

Skip the following fields for record data as they will be automatically augmented.

Contact Properties Integration (Tutorial)

Third party platforms can push contact properties to OnVoard. Synced properties can be used to:

In this walkthrough, we'll show an example on how we sync Stripe customer total spent.

1) Create Contact Property Types

Example Request

curl https://api.onvoard.com/v2/contact-property-types \
-X POST \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "key": "stripe_total_spent",
  "label": "Stripe Total Spent",
  "value_type": "NUMBER",
  "helper_text": "Stripe customer total spent in store currency."
}'

Example Response

{
  "id": "tx77k39xic9xjvy",
  "key": "custom_stripe_total_spent",
  "label": "Stripe Total Spent",
  "helper_text": "Stripe customer total spent in store currency.",
  "field_type": "",
  "value_type": "NUMBER",
  "definition_type": "CUSTOM"
}

First, we'll create a contact property type for stripe_total_spent.

2) Set Contact Property

Example Request

curl https://api.onvoard.com/v2/contacts \
-X POST \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "email": "jane@example.com",
  "properties": {
    "custom_stripe_total_spent": 1500
  }
}'

Example Response

{
  "id": "ct_qauejq13aixtowf",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "",
  "accepts_marketing_emails": false,
  "suppressed": false,
  "email_unsubscribed": false,
  "email_marked_as_spam": false,
  "email_hard_bounced": false,
  "email_soft_bounced_count": 0,
  "email_double_optin_status": "NOT_SET",
  "email_sendable": true,
  "email_double_opted_in": false,
  "created_datetime": "2021-12-23T03:40:40.495545Z",
  "modified_datetime": "2021-12-23T03:40:40.551498Z",
  "suppressed_datetime": null,
  "lists": [{
    "id": "ctlist_gf5gsfriphdcsdz",
    "name": "Newsletter"
  }],
  "tags": [{
    "id": "cttag_47ao13keno3rpsl",
    "name": "Premium"
  }],
  "segments": [],
  "properties": {
    "last_name": "Doe",
    "first_name": "Jane",
    "custom_username": "janedoe",
    "custom_stripe_total_spent": 1500.0
  }
}

OnVoard has a create or update contact endpoint which would allow you to save contact data with a single API call. We'll use this to save Stripe customer total spent.

Note: OnVoard will only update specified properties. As you can see from the example, custom_username remains intact.

Contacts

To save contact, we recommend using create or update contact endpoint which would allow you to save contact data with a single API call.

Contact Object

Represents a contact object. This is analogous to leads/subscribers/profiles/people in other platforms.

{
  "id": "ct_573taa9z5yd1iv7",
  "name": "",
  "email": "jane@example.com",
  "phone": "",
  "accepts_marketing_emails": false,
  "suppressed": false,
  "email_sendable": true,
  "email_unsubscribed": false,
  "email_marked_as_spam": false,
  "email_hard_bounced": false,
  "email_double_optin_status": "NOT_SET",
  "email_double_opted_in": false,
  "created_datetime": "2021-08-12T23:09:54.588927Z",
  "modified_datetime": "2021-08-12T23:09:54.595677Z",
  "suppressed_datetime": null,
  "lists": [],
  "tags": [],
  "segments": [{
    "id": "ctseg_wjhpj0oajkcmpdm",
    "name": "Not from EU"
  }],
  "properties": {
    "last_name": "",
    "first_name": ""
  }
}

Attributes

Field Type Description
id string Unique identifier for the object.
name string Name of contact.
email string Email of contact.
phone string Phone for contact.
accepts_marketing_emails boolean If contact is explicitly accepts marketing emails.
suppressed boolean If contact is suppressed. Suppressed contacts won't receive any message from you via OnVoard and will not be tracked.
email_sendable boolean If true, OnVoard will be able to send emails to this contact. Will be false if any of suppressed, email_unsubscribed, email_marked_as_spam, or email_hard_bounced is true. Will also be false if email_double_optin_status is NOT_CONFIRMED.
email_unsubscribed boolean If contact has unsubscribed from your emails.
email_marked_as_spam boolean If contact has marked your email as spam. If true, OnVoard will no longer attempt to send any emails to this contact.
email_hard_bounced boolean If previous emails sent to contact returns hard bounce error. If true, OnVoard will no longer attempt to send any emails to this contact.
email_double_optin_status enum (Email Double Optin Status) Email double-optin status.
email_double_opted_in boolean If contact is double opted-in for emails.
created_datetime string Datetime when contact was added to our system.
modified_datetime string Datetime when contact was last modified.
suppressed_datetime string Datetime when contact was suppressed. This will only be set if contact is suppressed.
lists[] object array (Contact List Object) Array of lists assigned to contact.
tags[] object array (Contact Tag Object) List of tags assigned to contact.
segments[] object array (Contact Segment Object) List of segments assigned to contact.
properties object Additional properties for contact in key-value format. See contact properties page. To specify custom properties, you need to first create a proptype via API or add proptype via console. Not all properties can be modified. We will only update specified properties. To unset a property, you can set it to null.

Contact List Object

Represents a contact list object.

{
  "id": "ctlist_2akm39pe38ye896",
  "name": "Newsletters"
}

Attributes

Field Type Description
id string Unique identifier for the object.
name string Name of contact list.

Contact Tag Object

Represents a contact tag object.

{
  "id": "cttag_j53r8tp7ds1eet8",
  "name": "Premium"
}

Attributes

Field Type Description
id string Unique identifier for the object.
name string Name of contact tag.

Contact Segment Object

Represents a contact segment object.

{
  "id": "ctseg_wjhpj0oajkcmpdm",
  "name": "Not from EU"
}

Attributes

Field Type Description
id string Unique identifier for the object.
name string Name of contact segment.

Enums

List of available enum types under this resource.

Email Double Optin Status

Default value is NOT_SET. If status is NOT_CONFIRMED, contact won't receive all other emails from you except for opt-in confirmation email.

Value Description
NOT_SET Not Set
NOT_CONFIRMED Not Confirmed
CONFIRMED Confirmed

Retrieve Contact

Example Request

curl https://api.onvoard.com/v2/contacts/ct_573taa9z5yd1iv7 \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "id": "ct_573taa9z5yd1iv7",
  "name": "",
  "email": "jane@example.com",
  "phone": "",
  "accepts_marketing_emails": false,
  "suppressed": false,
  "email_sendable": true,
  "email_unsubscribed": false,
  "email_marked_as_spam": false,
  "email_hard_bounced": false,
  "email_double_optin_status": "NOT_SET",
  "email_double_opted_in": false,
  "created_datetime": "2021-08-12T23:09:54.588927Z",
  "modified_datetime": "2021-08-12T23:09:54.595677Z",
  "suppressed_datetime": null,
  "lists": [],
  "tags": [],
  "segments": [{
    "id": "ctseg_wjhpj0oajkcmpdm",
    "name": "Not from EU"
  }],
  "properties": {
    "last_name": "",
    "first_name": ""
  }
}

Retrieve contact with given ID.

HTTP Request

GET https://api.onvoard.com/v2/contacts/:contact_id

Returns

Contact object if valid ID was provided.

Create Contact

Example Request

curl https://api.onvoard.com/v2/contacts \
-X POST \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "email": "jane@example.com",
  "name": "Jane Doe",
  "lists": ["ctlist_gf5gsfriphdcsdz"],
  "tags": ["Premium"]
}'

Example Response

{
  "id": "ct_q6tvy767v1vb8ig",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "",
  "accepts_marketing_emails": false,
  "suppressed": false,
  "email_sendable": true,
  "email_unsubscribed": false,
  "email_marked_as_spam": false,
  "email_hard_bounced": false,
  "email_double_optin_status": "NOT_SET",
  "email_double_opted_in": false,
  "created_datetime": "2021-12-23T03:40:40.495545Z",
  "modified_datetime": "2021-12-23T03:40:40.551498Z",
  "suppressed_datetime": null,
  "lists": [{
    "id": "ctlist_gf5gsfriphdcsdz",
    "name": "Newsletter"
  }],
  "tags": [{
    "id": "cttag_47ao13keno3rpsl",
    "name": "Premium"
  }],
  "segments": [],
  "properties": {
    "last_name": "Doe",
    "first_name": "Jane"
  }
}

Create a new contact.

HTTP Request

POST https://api.onvoard.com/v2/contacts

Returns

Created contact object if create succeeded.

Arguments

Field Type Required Description
email string Yes Email of contact. Must be unique within account.
name string No Name of contact.
phone string No Phone for contact.
accepts_marketing_emails boolean No If contact is explicitly accepts marketing emails. Default value is false.
email_unsubscribed boolean No If contact has unsubscribed from your emails. Default value is false.
email_double_optin_status enum (Email Double Optin Status) No Double-optin status for email. Default value is NOT_SET.
send_email_optin_confirmation boolean No Set true to send opt-in confirmation email if contact has not confirmed double opt-in. Before sending, we will override email_double_optin_status to NOT_CONFIRMED. This field will be ignored if contact's email_double_optin_status is CONFIRMED.
lists[] string array No Array of list IDs to assign contact.
tags[] string array No List of tag names to assign contact. For example: ["tag-1", "tag-2"]. Our system will automatically create new tag if name doesn't exist.
properties object No Additional properties for contact in key-value format. See contact properties page. To specify custom properties, you need to first create a proptype via API or add proptype via console. Not all properties can be modified. We will only update specified properties. To unset a property, you can set it to null.

Patch Contact

Suppressed contact can't be patched. You need to unsuppress a suppressed contact before you can patch.

Example Request

curl https://api.onvoard.com/v2/contacts/ct_573taa9z5yd1iv7 \
-X PATCH \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "name": "John Doe",
  "email_unsubscribed": true,
}'

Example Response

{
  "id": "ct_q6tvy767v1vb8ig",
  "name": "John Doe",
  "email": "jane@example.com",
  "phone": "",
  "accepts_marketing_emails": false,
  "suppressed": false,
  "email_sendable": false,
  "email_unsubscribed": true,
  "email_marked_as_spam": false,
  "email_hard_bounced": false,
  "email_double_optin_status": "NOT_SET",
  "email_double_opted_in": false,
  "created_datetime": "2021-12-23T03:40:40.495545Z",
  "modified_datetime": "2021-12-23T03:40:40.551498Z",
  "suppressed_datetime": null,
  "lists": [{
    "id": "ctlist_gf5gsfriphdcsdz",
    "name": "Newsletter"
  }],
  "tags": [{
    "id": "cttag_47ao13keno3rpsl",
    "name": "Premium"
  }],
  "segments": [],
  "properties": {
    "last_name": "Doe",
    "first_name": "John"
  }
}

Patch contact with given ID.

HTTP Request

PATCH https://api.onvoard.com/v2/contacts/:contact_id

Returns

Modified contact object if patch succeeded.

Arguments

Field Type Required Description
email string No Email of contact. Must be unique within account.
name string No Name of contact.
phone string No Phone for contact.
accepts_marketing_emails boolean No If contact is explicitly accepts marketing emails. Default value is false.
email_unsubscribed boolean No If contact has unsubscribed from your emails. Default value is false.
email_double_optin_status enum (Email Double Optin Status) No Double-optin status for email. Default value is NOT_SET.
send_email_optin_confirmation boolean No Set true to send opt-in confirmation email if contact has not confirmed double opt-in. Before sending, we will override email_double_optin_status to NOT_CONFIRMED. This field will be ignored if contact's email_double_optin_status is CONFIRMED.
lists[] string array No Array of list IDs to assign contact.
tags[] string array No List of tag names to assign contact. For example: ["tag-1", "tag-2"]. Our system will automatically create new tag if name doesn't exist.
properties object No Additional properties for contact in key-value format. See contact properties page. To specify custom properties, you need to first create a proptype via API or add proptype via console. Not all properties can be modified. We will only update specified properties. To unset a property, you can set it to null.

Delete Contact

Deleted contacts may still be tracked since they can be added back to the database. Use suppress if you need to erase contact's personal data and disable tracking permanently. Suppressed contact can't be deleted. You need to unsuppress a suppressed contact before you can delete.

Example Request

curl https://api.onvoard.com/v2/contacts/ct_q6tvy767v1vb8ig \
-X DELETE \
-H 'X-API-Key: {API_KEY}'

Example Response

{}

Delete contact with given ID.

HTTP Request

DELETE https://api.onvoard.com/v2/contacts/:contact_id

Create or Update Contact

Example Request

curl https://api.onvoard.com/v2/contacts \
-X POST \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "email": "jane@example.com",
  "name": "Jane Doe",
  "lists": ["ctlist_gf5gsfriphdcsdz"],
  "tags": ["Premium"]
}'

Example Response

{
  "id": "ct_qauejq13aixtowf",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "",
  "accepts_marketing_emails": false,
  "suppressed": false,
  "email_unsubscribed": false,
  "email_marked_as_spam": false,
  "email_hard_bounced": false,
  "email_double_optin_status": "NOT_SET",
  "email_sendable": true,
  "email_double_opted_in": false,
  "created_datetime": "2021-12-23T03:40:40.495545Z",
  "modified_datetime": "2021-12-23T03:40:40.551498Z",
  "suppressed_datetime": null,
  "lists": [{
    "id": "ctlist_gf5gsfriphdcsdz",
    "name": "Newsletter"
  }],
  "tags": [{
    "id": "cttag_47ao13keno3rpsl",
    "name": "Premium"
  }],
  "segments": [],
  "properties": {
    "last_name": "Doe",
    "first_name": "Jane"
  }
}

Create or update contact using email.

HTTP Request

POST https://api.onvoard.com/v2/contacts/create-or-update

Returns

Contact object if create or update succeeded.

Arguments

Field Type Required Description
email string Yes Email of contact. We will use email to uniquely identify contact to create or update.
name string No Name of contact.
phone string No Phone for contact.
accepts_marketing_emails boolean No If contact is explicitly accepts marketing emails. Default value is false.
email_unsubscribed boolean No If contact has unsubscribed from your emails. Default value is false.
email_double_optin_status enum (Email Double Optin Status) No Double-optin status for email. Default value is NOT_SET.
send_email_optin_confirmation boolean No Set true to send opt-in confirmation email if contact has not confirmed double opt-in. Before sending, we will override email_double_optin_status to NOT_CONFIRMED. This field will be ignored if contact's email_double_optin_status is CONFIRMED.
lists[] string array No Array of list IDs to assign contact.
tags[] string array No List of tag names to assign contact. For example: ["tag-1", "tag-2"]. Our system will automatically create new tag if name doesn't exist.
properties object No Additional properties for contact in key-value format. See contact properties page. To specify custom properties, you need to first create a proptype via API or add proptype via console. Not all properties can be modified. We will only update specified properties. To unset a property, you can set it to null.

Suppress Contact

Suppressed contacts are users who want to be forgotten by your business. When contact is suppressed, we will erase all data associated to them. They won't receive any message from you via OnVoard and will not be tracked. You can only unsuppress a suppressed contact. They can't be modified in any other ways and can't be deleted.

Example Request

curl https://api.onvoard.com/v2/contacts/ct_hws9idjxuiiui6r/suppress \
-X POST \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "id": "ct_q6tvy767v1vb8ig",
  "name": "John Doe",
  "email": "jane@example.com",
  "phone": "",
  "accepts_marketing_emails": false,
  "suppressed": true,
  "email_sendable": false,
  "email_unsubscribed": false,
  "email_marked_as_spam": false,
  "email_hard_bounced": false,
  "email_double_optin_status": "NOT_SET",
  "email_double_opted_in": false,
  "created_datetime": "2021-12-23T03:40:40.495545Z",
  "modified_datetime": "2021-12-23T03:40:40.551498Z",
  "suppressed_datetime": null,
  "lists": [],
  "tags": [],
  "segments": [],
  "properties": {
    "last_name": "Doe",
    "first_name": "John"
  }
}

Suppress contact with given ID.

HTTP Request

POST https://api.onvoard.com/v2/contacts/:contact_id/suppress

Returns

Modified contact object if suppress succeeded.

Unsuppress Contact

Example Request

curl https://api.onvoard.com/v2/contacts/ct_hws9idjxuiiui6r/unsuppress \
-X POST \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "id": "ct_q6tvy767v1vb8ig",
  "name": "John Doe",
  "email": "jane@example.com",
  "phone": "",
  "accepts_marketing_emails": false,
  "suppressed": false,
  "email_sendable": true,
  "email_unsubscribed": false,
  "email_marked_as_spam": false,
  "email_hard_bounced": false,
  "email_double_optin_status": "NOT_SET",
  "email_double_opted_in": false,
  "created_datetime": "2021-12-23T03:40:40.495545Z",
  "modified_datetime": "2021-12-23T03:40:40.551498Z",
  "suppressed_datetime": null,
  "lists": [],
  "tags": [],
  "segments": [],
  "properties": {
    "last_name": "Doe",
    "first_name": "John"
  }
}

Unsuppress contact with given ID.

HTTP Request

POST https://api.onvoard.com/v2/contacts/:contact_id/unsuppress

Returns

Modified contact object if unsuppress succeeded.

List all Contacts

Example Request

curl https://api.onvoard.com/v2/contacts \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "current_page": 1,
  "page_size": 10,
  "results": [{
    "id": "ct_573taa9z5yd1iv7",
    "name": "",
    "email": "jane@example.com",
    "phone": "",
    "accepts_marketing_emails": false,
    "suppressed": false,
    "email_sendable": true,
    "email_unsubscribed": false,
    "email_marked_as_spam": false,
    "email_hard_bounced": false,
    "email_double_optin_status": "NOT_SET",
    "email_double_opted_in": false,
    "created_datetime": "2021-08-12T23:09:54.588927Z",
    "modified_datetime": "2021-08-12T23:09:54.595677Z",
    "suppressed_datetime": null,
    "lists": [],
    "tags": [],
    "segments": [{
      "id": "ctseg_wjhpj0oajkcmpdm",
      "name": "Not from EU"
    }],
    "properties": {
      "last_name": "",
      "first_name": ""
    }
  }]
}

List all contacts user have access to. Records are sorted by created_datetime, starting from most recent contacts. To retrieve active contacts that can receive emails, specify true for email_sendable.

HTTP Request

GET https://api.onvoard.com/v2/contacts

Returns

List of contact objects.

Arguments

Field Type Description
id string Filter by id.
email string Filter by email.
keyword string Filter by specific keyword.
accepts_marketing_emails boolean Use true or false to filter.
suppressed boolean Use true or false to filter.
email_sendable boolean Use true or false to filter.
email_unsubscribed boolean Use true or false to filter.
email_marked_as_spam boolean Use true or false to filter.
email_hard_bounced boolean Use true or false to filter.
list_ids string Comma-seperated list of Contact List IDs to filter with. Use this to retrieve contacts from specific lists.
tag_ids string Comma-seperated list of Contact Tag IDs to filter with. Use this to retrieve contacts from specific tags.
segment_ids string Comma-seperated list of Contact Segment IDs to filter with. Use this to retrieve contacts from specific segments.
created_before integer Filter contacts created before provided timestamp.
created_after integer Filter contacts created after provided timestamp.
page integer Traverse to specific page. Page index starts from 1.
page_size integer Number of records you want to return for each page. Can be from 1 to 100. Default is 10.

Contact Property Types

Before you can add custom property for contact, you need to create a property type (proptype). For example, if you intend to use total_spent as a property, you need to create proptype for that. You can think of contact proptypes as a schema for allowed contact properties.

By default, OnVoard creates a set of predefined contact proptypes. All additional contact proptypes that are created by you will be classified as custom contact proptypes.

Contact Property Type Object

Represents a contact property type object.

{
  "id": "2ixqzwl61rkyzso",
  "key": "name",
  "label": "Name",
  "helper_text": "Name of contact.",
  "field_type": "TEXT",
  "value_type": "STRING",
  "definition_type": "PREDEFINED"
}

Attributes

Field Type Description
id string Unique identifier for the object.
key string Key must be lowercase alphanumeric characters and underscores only. Specified key can't be changed later.
label string Label for proptype.
helper_text string Additional information to describe this proptype.
field_type enum (Property Field Type) The field type to be used for this proptype.
value_type enum (Property Value Type) The value type to be used for this proptype.
definition_type enum (Contact Property Definition Type) The definition type to be used for this proptype.

Enums

List of available enum types under this resource.

Contact Property Definition Type

Value Description
PREDEFINED Predefined
CUSTOM Custom

Retrieve Contact Property Type

Example Request

curl https://api.onvoard.com/v2/contact-property-types/2ixqzwl61rkyzso \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "id": "2ixqzwl61rkyzso",
  "key": "name",
  "label": "Name",
  "helper_text": "Name of contact.",
  "field_type": "TEXT",
  "value_type": "STRING",
  "definition_type": "PREDEFINED"
}

Retrieve contact property type with given ID.

HTTP Request

GET https://api.onvoard.com/v2/contact-property-types/:contact_proptype_id

Returns

Contact Property Type object if valid ID was provided.

Create Contact Property Type

All created contact proptypes will have CUSTOM for definition type. You can view them at custom contact properties page.

Example Request

curl https://api.onvoard.com/v2/contact-property-types \
-X POST \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "key": "username",
  "label": "Username",
  "value_type": "STRING",
  "helper_text": "Username for contact to access store."
}'

Example Response

{
  "id": "wcu6uv513hz58ea",
  "key": "custom_username",
  "label": "Username",
  "helper_text": "Username for contact to access store.",
  "field_type": "",
  "value_type": "STRING",
  "definition_type": "CUSTOM"
}

Create a new contact property type.

HTTP Request

POST https://api.onvoard.com/v2/contact-property-types

Returns

Created contact property type object if create succeeded.

Arguments

Field Type Required Description
key string Yes Our system will automatically prefix key with custom_. This is to prevent name collision with predefined proptypes. Provided key must be lowercase alphanumeric characters and underscores only. Specified key can't be changed later.
label string Yes Human readable label for proptype.
value_type enum (Property Value Type) Yes The value type to be used for this proptype.
field_type enum (Property Field Type) No Specify field type if you need additional validation. For example, use EMAIL to validate for email property value.
helper_text string No Additional information to describe proptype.

Patch Contact Property Type

You can only patch record for contact with CUSTOM type and OBJECT kind.

Example Request

curl https://api.onvoard.com/v2/contact-property-types/rsrcd_qx1w4ytagd8lf34 \
-X PATCH \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "helper_text": ""
}'

Example Response

{
  "id": "wcu6uv513hz58ea",
  "key": "custom_username",
  "label": "Username",
  "helper_text": "",
  "field_type": "",
  "value_type": "STRING",
  "definition_type": "CUSTOM"
}

Patch contact property type with given ID.

HTTP Request

PATCH https://api.onvoard.com/v2/contact-property-types/:contact_proptype_id

Returns

Modified contact property type object if patch succeeded.

Arguments

Field Type Required Description
label string No Human readable label for proptype.
helper_text string No Additional information to describe proptype.

Delete Contact Property Type

Example Request

curl https://api.onvoard.com/v2/contact-property-types/wcu6uv513hz58ea \
-X DELETE \
-H 'X-API-Key: {API_KEY}'

Example Response

{}

Delete contact property type with given ID. You can only delete custom proptype.

HTTP Request

DELETE https://api.onvoard.com/v2/contact-property-types/:contact_proptype_id

List all Contact Property Types

Example Request

curl https://api.onvoard.com/v2/contact-property-types \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "current_page": 1,
  "page_size": 10,
  "results": [{
    "id": "2ixqzwl61rkyzso",
    "key": "name",
    "label": "Name",
    "helper_text": "Name of contact.",
    "field_type": "TEXT",
    "value_type": "STRING",
    "definition_type": "PREDEFINED"
  }]
}

List all contact property types user have access to.

HTTP Request

GET https://api.onvoard.com/v2/contact-property-types

Returns

List of contact property types objects.

Arguments

Field Type Description
id string Filter by id.
keyword string Filter by specific keyword.
field_type enum (Property Field Type) Filter by field type.
value_type enum (Property Value Type) Filter by value type.
definition_type enum (Contact Property Definition Type) Filter by definition type.
page integer Traverse to specific page. Page index starts from 1.
page_size integer Number of records you want to return for each page. Can be from 1 to 100. Default is 10.

Contact Activities

On top of providing insights, there are 2 main use cases for contact activities.

Segmentation - You can use activities to segment contacts. For example, if a contact has order_placed activity within the last 7 days, we can add contact to Recent Customer segment.

Trigger Workflows - Sometimes, it may be handy to perform some tasks after an activity has occured. For example, if order_placed activity is created for a contact, we can use workflow to automatically sent a review request email 3 days later.

See guide for contact activities.

Contact Activity Object

Represents a contact activity object.

{
  "id": "ctact_zber4co2k1lme1m1yztk",
  "contact": {
    "id": "ct_99pjwz4m1sx9ej8",
    "email": "jane@example.com"
  },
  "type": "email_opened",
  "datetime": "2021-12-20T07:56:03Z",
  "record_data": {
    "activity_id": "ctact_zber4co2k1lme1m1yztk",
    "activity_datetime": 1639986963,
    "contact_id": "ct_99pjwz4m1sx9ej8",
    "contact_email": "jane@example.com",
    "email_id": "em_vd5rmbu15cktuiz",
    "email_name": "still-mouse-1358",
    "broadcast_id": "brd_n80lwnvxpolpm26",
    "recipient_id": "erpt_uumm1bputajjjdd",
    "broadcast_token": "shrill-queen-1328"
  }
}

Attributes

Field Type Description
id string Unique identifier for the object.
contact.id string Unique identifier of contact.
contact.email string Email of contact.
type string Accessor for activity type.
datetime string Datetime when activity occured.
record_data object Resource record data for activity. Go to resources page to view list of available properties for activity type.

Retrieve Contact Activity

Example Request

curl https://api.onvoard.com/v2/contact-activities/ctact_zber4co2k1lme1m1yztk \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "id": "ctact_zber4co2k1lme1m1yztk",
  "contact": {
    "id": "ct_99pjwz4m1sx9ej8",
    "email": "jane@example.com"
  },
  "type": "email_opened",
  "datetime": "2021-12-20T07:56:03Z",
  "record_data": {
    "activity_id": "ctact_zber4co2k1lme1m1yztk",
    "activity_datetime": 1639986963,
    "contact_id": "ct_99pjwz4m1sx9ej8",
    "contact_email": "jane@example.com",
    "email_id": "em_vd5rmbu15cktuiz",
    "email_name": "still-mouse-1358",
    "broadcast_id": "brd_n80lwnvxpolpm26",
    "recipient_id": "erpt_uumm1bputajjjdd",
    "broadcast_token": "shrill-queen-1328"
  }
}

Retrieve contact activity with given ID.

HTTP Request

GET https://api.onvoard.com/v2/contact-activities/:contact_activity_id

Returns

Contact Activity object if valid ID was provided.

Create Contact Activity

Activties can only be added for custom activity type. To create new acitvity type, you can either create via API or go to custom activities page to add new custom activity type.

Skip the following fields for record data as they will be automatically augmented.

Example Request

curl https://api.onvoard.com/v2/contact-activities \
-X POST \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "contact_email": "jane@example.com",
  "type": "custom.wishlist_item_added",
  "record_data": {
    "wishlist_id": "12345",
    "wishlist_name": "Toy Collectibles",
    "product_id": "56789",
    "product_name": "Spiderman Mini"
  }
}'

Example Response

{
  "id": "ctact_umqp4rp7x9e3kzg8etpi",
  "contact": {
    "id": "ct_hws9idjxuiiui6r",
    "email": "jane@example.com"
  },
  "type": "custom.wishlist_item_added",
  "datetime": "2021-12-20T07:56:03Z",
  "record_data": {
    "activity_id": "ctact_umqp4rp7x9e3kzg8etpi",
    "activity_datetime": 1593591541,
    "contact_id": "ct_hws9idjxuiiui6r",
    "contact_email": "jane@example.com",
    "wishlist_id": "12345",
    "wishlist_name": "Toy Collectibles",
    "product_name": "Spiderman Mini",
    "product_id": "56789"
  }
}

Create a new contact activity.

HTTP Request

POST https://api.onvoard.com/v2/contact-activities

Returns

Created contact activity object if create succeeded.

Arguments

Field Type Required Description
contact_id string Maybe ID of contact to associate with activity. Either contact_id or contact_email must be provided.
contact_email string Maybe Email of contact to associate with activity. We will automatically create new contact using email if it doesn't exists. Either contact_id or contact_email must be provided.
type string Yes Accessor for contact activity type.
timestamp integer No Timestamp when activity occured. If not provided, we will use current timestamp.
record_data object No Resource record data for activity. Go to custom contact activities page to view list of available properties for activity type.

Delete Contact Activity

Example Request

curl https://api.onvoard.com/v2/contact-activity/ctact_umqp4rp7x9e3kzg8etpi \
-X DELETE \
-H 'X-API-Key: {API_KEY}'

Example Response

{}

Delete contact activity with given ID. Only custom activities can be deleted.

HTTP Request

DELETE https://api.onvoard.com/v2/contact-activity/:contact_activity_id

List all Contact Activities

Example Request

curl https://api.onvoard.com/v2/contact-activities \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "current_page": 1,
  "page_size": 10,
  "results": [{
    "id": "ctact_umqp4rp7x9e3kzg8etpi",
    "contact": {
      "id": "ct_hws9idjxuiiui6r",
      "email": "jane@example.com"
    },
    "type": "custom.wishlist_item_added",
    "datetime": "2021-12-20T07:56:03Z",
    "record_data": {
      "activity_id": "ctact_umqp4rp7x9e3kzg8etpi",
      "activity_datetime": 1593591541,
      "contact_id": "ct_hws9idjxuiiui6r",
      "contact_email": "jane@example.com",
      "wishlist_id": "12345",
      "wishlist_name": "Toy Collectibles",
      "product_name": "Spiderman Mini",
      "product_id": "56789"
    }
  }]
}

List all contact activities user have access to. Records are sorted by datetime, starting from most recent activities.

HTTP Request

GET https://api.onvoard.com/v2/contact-activities

Returns

List of contact actvities objects.

Arguments

Field Type Description
id string Filter by id.
contact_id string Contact ID to filter. Use this to retrieve activities from a specific contact.
contact_email string Contact Email to filter. Use this to retrieve activities from a specific contact.
keyword string Filter by specific keyword.
activity_types string Comma-seperated list of Activity Type Accessors to filter with. For example, email_opened,custom.wishlist_item_added
before integer Filter activities before provided timestamp.
after integer Filter activities after provided timestamp.
page integer Traverse to specific page. Page index starts from 1.
page_size integer Number of records you want to return for each page. Can be from 1 to 100. Default is 10.

Contact Activity Types

Contact activity types refers to the available types of contact activities. Activity type has a one-to-one relation with resource.

Contact Activity Type Object

Represents a contact activity type object.

{
  "id": "catype_1v8jmq0vrnx20g8",
  "resource": {
    "id": "resrc_7gjseix9l3p59qv",
    "namespace": "",
    "key": "email_link_clicked",
    "accessor": "email_link_clicked",
    "name": "Email Link Clicked",
    "helper_text": "When an email link has been clicked by contact.",
    "type": "ONVOARD",
    "kind": "ACTIVITY",
    "icon_type": "NATIVE",
    "icon_class": "envelope",
    "icon_media": null
  },
  "descriptor_template": "{{ email_name }}"
}

Attributes

Field Type Description
id string Unique identifier for the object.
resource object (Resource Object) Resource used for contact activity. This is a one-to-one relation.
descriptor_template string Used to generate descriptor that will be shown in contact's profile timeline to provide additional details.You can use liquid templating to render output. Activity record properties can be used as variables. See guide for descriptor template

Retrieve Contact Activity Type

Example Request

curl https://api.onvoard.com/v2/contact-activity-types/2ixqzwl61rkyzso \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "id": "catype_1v8jmq0vrnx20g8",
  "resource": {
    "id": "resrc_7gjseix9l3p59qv",
    "namespace": "",
    "key": "email_link_clicked",
    "accessor": "email_link_clicked",
    "name": "Email Link Clicked",
    "helper_text": "When an email link has been clicked by contact.",
    "type": "ONVOARD",
    "kind": "ACTIVITY",
    "icon_type": "NATIVE",
    "icon_class": "envelope",
    "icon_media": null
  },
  "descriptor_template": "{{ email_name }}"
}

Retrieve contact activity type with given ID.

HTTP Request

GET https://api.onvoard.com/v2/contact-activity-types/:activity_type_id

Returns

Contact Activity Type object if valid ID was provided.

Create Contact Activity Type

Example Request

curl https://api.onvoard.com/v2/contact-activity-types \
-X POST \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "resource": "resrc_7au3qy6ii5ii78y",
  "descriptor_template": "Stripe checkout for {{ contact_email }}"
}'

Example Response

{
  "id": "catype_5jfqj3nw12nd6mp",
  "resource": {
    "id": "resrc_7au3qy6ii5ii78y",
    "namespace": "custom",
    "key": "stripe_customer_checkout",
    "accessor": "custom.stripe_customer_checkout",
    "name": "Stripe Customer Checkout",
    "helper_text": "Represents Stripe Customer Checkout activity.",
    "type": "CUSTOM",
    "kind": "ACTIVITY",
    "icon_type": "UPLOADED",
    "icon_class": "",
    "icon_media": {
      "id": "file_atbo6hy2k6kdla6",
      "file_url": "https://storage.googleapis.com/onvoard/upload/resource/icon-media/52d168691222d580626b91f.jpeg",
      "created_datetime": "2021-12-25T13:20:04.449180Z",
      "height": 200,
      "width": 200
    }
  },
  "descriptor_template": "Stripe checkout for {{ contact_email }}"
}

Create a new contact activity type. Prerequisite: Before creating contact activity type, you should create resource that will be linked. \

HTTP Request

POST https://api.onvoard.com/v2/contact-activity-types

Returns

Created contact activity type object if create succeeded.

Arguments

Field Type Required Description
resource string Yes ID of resource to associate with activity type.
descriptor_template string No Used to generate descriptor that will be shown in contact's profile timeline to provide additional details.You can use liquid templating to render output. Activity record properties can be used as variables. See guide for descriptor template

Patch Contact Activity Type

You can only patch record for contact with CUSTOM type and OBJECT kind.

Example Request

curl https://api.onvoard.com/v2/contact-activity-types/catype_5jfqj3nw12nd6mp \
-X PATCH \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "descriptor_template": ""
}'

Example Response

{
  "id": "catype_5jfqj3nw12nd6mp",
  "resource": {
    "id": "resrc_7au3qy6ii5ii78y",
    "namespace": "custom",
    "key": "stripe_customer_checkout",
    "accessor": "custom.stripe_customer_checkout",
    "name": "Stripe Customer Checkout",
    "helper_text": "Represents Stripe Customer Checkout activity.",
    "type": "CUSTOM",
    "kind": "ACTIVITY",
    "icon_type": "UPLOADED",
    "icon_class": "",
    "icon_media": {
      "id": "file_atbo6hy2k6kdla6",
      "file_url": "https://storage.googleapis.com/onvoard/upload/resource/icon-media/52d168691222d580626b91f.jpeg",
      "created_datetime": "2021-12-25T13:20:04.449180Z",
      "height": 200,
      "width": 200
    }
  },
  "descriptor_template": ""
}

Patch contact activity type with given ID.

HTTP Request

PATCH https://api.onvoard.com/v2/contact-activity-types/:activity_type_id

Returns

Modified contact activity type object if patch succeeded.

Arguments

Field Type Required Description
descriptor_template string No Used to generate descriptor that will be shown in contact's profile timeline to provide additional details.You can use liquid templating to render output. Activity record properties can be used as variables. See guide for descriptor template

Delete Contact Activity Type

Example Request

curl https://api.onvoard.com/v2/contact-activity-types/catype_5jfqj3nw12nd6mp \
-X DELETE \
-H 'X-API-Key: {API_KEY}'

Example Response

{}

Delete contact activity type with given ID. Only custom activity type can be deleted.

Important: If activity type is deleted, we will purge all linked activities and resource records. You should only delete activity type if you are certain that you won't be using it anymore.

HTTP Request

DELETE https://api.onvoard.com/v2/contact-activity-types/:activity_type_id

List all Contact Activity Types

Example Request

curl https://api.onvoard.com/v2/contact-activity-types \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "current_page": 1,
  "page_size": 10,
  "results": [{
    "id": "catype_1v8jmq0vrnx20g8",
    "resource": {
      "id": "resrc_7gjseix9l3p59qv",
      "namespace": "",
      "key": "email_link_clicked",
      "accessor": "email_link_clicked",
      "name": "Email Link Clicked",
      "helper_text": "When an email link has been clicked by contact.",
      "type": "ONVOARD",
      "kind": "ACTIVITY",
      "icon_type": "NATIVE",
      "icon_class": "envelope",
      "icon_media": null
    },
    "descriptor_template": "{{ email_name }}"
  }]
}

List all contact activity types user have access to.

HTTP Request

GET https://api.onvoard.com/v2/contact-activity-types

Returns

List of contact activity types objects.

Arguments

Field Type Description
id string Filter by id.
keyword string Filter by specific keyword.
resource_type enum (Resource Type) Filter by resource type.
accessor string Filter by specific accessor. For example email_opened, stripe.customer.
page integer Traverse to specific page. Page index starts from 1.
page_size integer Number of records you want to return for each page. Can be from 1 to 100. Default is 10.

Resources

See guide for resources. You can query all available resources for an account. However, only custom resource can be create or modify. In general, resource is used to store data for integration. For example, by adding stripe_customer_checkout activity resource, marketers can use this activity as workflow trigger. This allows them to follow-up with post-purchase emails when a Stripe customer checks out.

Resource Object

Represents a resource object.

{
  "id": "resrc_yt7z2wzcoxbimb2",
  "namespace": "shopify",
  "key": "customer",
  "accessor": "shopify.customer",
  "name": "Shopify Customer",
  "helper_text": "Resource to represent Shopify Customer.",
  "type": "EXTERNAL",
  "kind": "OBJECT",
  "icon_type": "NATIVE",
  "icon_class": "",
  "icon_media": null
}

Attributes

Field Type Description
id string Unique identifier for the object.
accessor string Accessor is used to uniquely identify each resources within an account. For resource with ONVOARD type, accessor will be same as key, such as contact_list, email_delivered. For resource with EXTERNAL and CUSTOM type, it will be in the format [namespace].[key], such as shopify.customer, custom.wishlist_item_added.
namespace string Namespace for resource. For resource with ONVOARD type, namespace will be empty. For resource with CUSTOM type, namespace will be custom.
key string Key for resource.
name string Name for resource.
helper_text string Helper text to describe resource.
type enum (Resource Type) Type for this resource.
kind enum (Resource Kind) Kind for this resource.
icon_type enum (Resource Icon Type) Icon type for this resource.
icon_class string Icon class for this resource. Only applicable when using NATIVE icon type.
icon_media object (Image Media Object) Image for icon. Used for UPLOADED icon type

Enums

List of available enum types under this resource.

Resource Type

Value Description
ONVOARD OnVoard
EXTERNAL External
CUSTOM Custom

Resource Kind

Value Description
OBJECT Object
ACTIVITY Activity

Resource Icon Type

Value Description
NATIVE Native
UPLOADED Uploaded

Retrieve Resource

Example Request

curl https://api.onvoard.com/v2/resources/resrc_iodvczkh5jf5do1 \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "id": "resrc_iodvczkh5jf5do1",
  "accessor": "shopify.customer",
  "namespace": "shopify",
  "key": "customer",
  "name": "Shopify Customer",
  "helper_text": "Resource to represent Shopify Customer.",
  "type": "EXTERNAL",
  "kind": "OBJECT"
}

Retrieve resource with given ID.

HTTP Request

GET https://api.onvoard.com/v2/resources/:resource_id

Returns

Resource object if valid ID was provided.

Create Resource

Example Request

curl https://api.onvoard.com/v2/resources \
-X POST \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "key": "stripe_customer_checkout",
  "name": "Stripe Customer Checkout",
  "kind": "ACTIVITY",
  "icon_type": "UPLOADED",
  "icon_url": "https://pbs.twimg.com/profile_images/1422297335531376654/f0wnwzb-_200x200.jpg"
}'

Example Response

{
  "id": "resrc_7au3qy6ii5ii78y",
  "namespace": "custom",
  "key": "stripe_customer_checkout",
  "accessor": "custom.stripe_customer_checkout",
  "name": "Stripe Customer Checkout",
  "helper_text": "",
  "type": "CUSTOM",
  "kind": "ACTIVITY",
  "icon_type": "UPLOADED",
  "icon_class": "",
  "icon_media": {
    "id": "file_atbo6hy2k6kdla6",
    "file_url": "https://storage.googleapis.com/onvoard/upload/resource/icon-media/52d168691d580626b91f.jpeg",
    "created_datetime": "2021-12-25T13:20:04.449180Z",
    "height": 200,
    "width": 200
  }
}

Create a new resource. All created resource will be in CUSTOM type with custom namespace.

HTTP Request

POST https://api.onvoard.com/v2/resources

Returns

Created resource object if create succeeded.

Arguments

Field Type Required Description
name string Yes Name for resource.
key string Yes Key for resource. must be lowercase alphanumeric characters and underscores only. Specified key can't be changed later. We recommend prefixing with your own brand. For example, paypal_customer_checkout.
kind enum (Resource Kind) Yes Kind of resource. For contact activity, specify ACTIVITY. Can't be changed later.
icon_type enum (Resource Icon Type) Yes Icon type for this resource.
icon_class string No Icon class for this resource. For example, add, badge, bank-account. Go to blueprint icons page to view available icons. Must be specified if icon_type is NATIVE.
icon_url string No Image url for resource icon. Use this to specify your own icon for resource. Must be specified if icon_type is UPLOADED.
helper_text string No Additional information to describe resource.

Patch Resource

Example Request

curl https://api.onvoard.com/v2/resources/rvw_rmkoqmzo8f511re \
-X PATCH \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "helper_text": "Represents Stripe Customer Checkout activity."
}'

Example Response

{
  "id": "resrc_7au3qy6ii5ii78y",
  "namespace": "custom",
  "key": "stripe_customer_checkout",
  "accessor": "custom.stripe_customer_checkout",
  "name": "Stripe Customer Checkout",
  "helper_text": "Represents Stripe Customer Checkout activity.",
  "type": "CUSTOM",
  "kind": "ACTIVITY",
  "icon_type": "UPLOADED",
  "icon_class": "",
  "icon_media": {
    "id": "file_atbo6hy2k6kdla6",
    "file_url": "https://storage.googleapis.com/onvoard/upload/resource/icon-media/52d168691d580626b91f.jpeg",
    "created_datetime": "2021-12-25T13:20:04.449180Z",
    "height": 200,
    "width": 200
  }
}

Patch resource with given ID.

HTTP Request

PATCH https://api.onvoard.com/v2/resources/:resource_id

Returns

Modified resource object if patch succeeded.

Arguments

Field Type Required Description
name string No Name for resource.
icon_type enum (Resource Icon Type) No Icon type for this resource.
icon_class string No Icon class for this resource. For example, add, badge, bank-account. Go to blueprint icons page to view available icons. Must be specified if icon_type is NATIVE.
icon_url string No Image url for resource icon. Use this to specify your own icon for resource. Must be specified if icon_type is UPLOADED.
helper_text string No Additional information to describe resource.

List all Resources

Example Request

curl https://api.onvoard.com/v2/resources \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "current_page": 1,
  "page_size": 10,
  "results": [{
    "id": "resrc_yt7z2wzcoxbimb2",
    "namespace": "shopify",
    "key": "customer",
    "accessor": "shopify.customer",
    "name": "Shopify Customer",
    "helper_text": "Resource to represent Shopify Customer.",
    "type": "EXTERNAL",
    "kind": "OBJECT",
    "icon_type": "NATIVE",
    "icon_class": "",
    "icon_media": null
  }]
}

List all resources user have access to.

HTTP Request

GET https://api.onvoard.com/v2/resources

Returns

List of resource objects.

Arguments

Field Type Description
id string Filter by id.
keyword string Filter by specific keyword.
type enum (Resource Type) Filter by resource type.
kind enum (Resource Kind) Filter by resource kind.
accessor string Filter by specific accessor. For example email_opened, stripe.customer.
page integer Traverse to specific page. Page index starts from 1.
page_size integer Number of records you want to return for each page. Can be from 1 to 100. Default is 10.

Resource Property Types

After creating a custom resource, you need to specify property type (proptype) before you can add record property. For example, if you intend to use total_spent as a property, you need to create proptype for that. You can think of resource proptypes as a schema for allowed properties.

When you create a resource with ACTIVITY kind, OnVoard will automatically add the following proptypes.

Resource Property Type Object

Represents a resource property type object.

{
  "id": "39b439j131ndv2f",
  "key": "first_name",
  "label": "First Name",
  "helper_text": "The customer's first name.",
  "field_type": "TEXT",
  "value_type": "STRING",
  "resource_id": "resrc_yt7z2wzcoxbimb2",
  "resource_accessor": "shopify.customer"
}

Attributes

Field Type Description
id string Unique identifier for the object.
key string Key must be lowercase alphanumeric characters and underscores only. Specified key can't be changed later.
label string Label for proptype.
helper_text string Additional information to describe this proptype.
field_type enum (Property Field Type) The field type to be used for this proptype.
value_type enum (Property Value Type) The value type to be used for this proptype.
resource_id string Unique identifier for linked resource.
resource_accessor string Accessor for linked resource.

Retrieve Resource Property Type

Example Request

curl https://api.onvoard.com/v2/resource-property-types/39b439j131ndv2f \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "id": "39b439j131ndv2f",
  "key": "first_name",
  "label": "First Name",
  "helper_text": "The customer's first name.",
  "field_type": "TEXT",
  "value_type": "STRING",
  "resource_id": "resrc_yt7z2wzcoxbimb2",
  "resource_accessor": "shopify.customer"
}

Retrieve resource property type with given ID.

HTTP Request

GET https://api.onvoard.com/v2/resource-property-types/:resource_proptype_id

Returns

Resource Property Type object if valid ID was provided.

Create Resource Property Type

You can only add property type for resources with CUSTOM type.

Example Request

curl https://api.onvoard.com/v2/resource-property-types \
-X POST \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "resource": "resrc_7au3qy6ii5ii78y",
  "key": "total_spent",
  "label": "Total Spent",
  "value_type": "NUMBER",
  "helper_text": "Total spent for order"
}'

Example Response

{
  "id": "oqy8kx1b2k4rgrn",
  "key": "total_spent",
  "label": "Total Spent",
  "helper_text": "Total spent for order",
  "field_type": "",
  "value_type": "NUMBER",
  "resource_id": "resrc_7au3qy6ii5ii78y",
  "resource_accessor": "custom.stripe_customer_checkout"
}

Create a new resource property type.

HTTP Request

POST https://api.onvoard.com/v2/resource-property-types

Returns

Created resource property type object if create succeeded.

Arguments

Field Type Required Description
resource string Yes ID for linked resource.
key string Yes Key must be lowercase alphanumeric characters and underscores only. Specified key can't be changed later.
label string Yes Human readable label for proptype.
value_type enum (Property Value Type) Yes The value type to be used for this proptype.
field_type enum (Property Field Type) No Specify field type if you need additional validation. For example, use EMAIL to validate for email property value.
helper_text string No Additional information to describe proptype.

Patch Resource Property Type

You can only patch record for resource with CUSTOM type and OBJECT kind.

Example Request

curl https://api.onvoard.com/v2/resource-property-types/rsrcd_qx1w4ytagd8lf34 \
-X PATCH \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "helper_text": ""
}'

Example Response

{
  "id": "oqy8kx1b2k4rgrn",
  "key": "total_spent",
  "label": "Total Spent",
  "helper_text": "",
  "field_type": "",
  "value_type": "NUMBER",
  "resource_id": "resrc_7au3qy6ii5ii78y",
  "resource_accessor": "custom.stripe_customer_checkout"
}

Patch resource property type with given ID.

HTTP Request

PATCH https://api.onvoard.com/v2/resource-property-types/:resource_proptype_id

Returns

Modified resource property type object if patch succeeded.

Arguments

Field Type Required Description
label string No Human readable label for proptype.
helper_text string No Additional information to describe proptype.

Delete Resource Property Type

Example Request

curl https://api.onvoard.com/v2/resource-property-types/oqy8kx1b2k4rgrn \
-X DELETE \
-H 'X-API-Key: {API_KEY}'

Example Response

{}

Delete resource property type with given ID. You can only delete custom proptype.

HTTP Request

DELETE https://api.onvoard.com/v2/resource-property-types/:resource_proptype_id

List all Resource Property Types

Example Request

curl https://api.onvoard.com/v2/resource-property-types \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "current_page": 1,
  "page_size": 10,
  "results": [{
    "id": "39b439j131ndv2f",
    "key": "first_name",
    "label": "First Name",
    "helper_text": "The customer's first name.",
    "field_type": "TEXT",
    "value_type": "STRING",
    "resource_id": "resrc_yt7z2wzcoxbimb2",
    "resource_accessor": "shopify.customer"
  }]
}

List all resource property types user have access to.

HTTP Request

GET https://api.onvoard.com/v2/resource-property-types

Returns

List of resource property types objects.

Arguments

Field Type Description
id string Filter by id.
resource_id string Resource ID to filter. Use this to retrieve records from a specific resource.
resource_accessor string Resource Accessor to filter. Use this to retrieve records from a specific resource.
keyword string Filter by specific keyword.
field_type enum (Property Field Type) Filter by field type.
value_type enum (Property Value Type) Filter by value type.
page integer Traverse to specific page. Page index starts from 1.
page_size integer Number of records you want to return for each page. Can be from 1 to 100. Default is 10.

Resource Records

While you can query for all resouce records from an account, we only allow adding records for custom resource. Before adding a record, you should create proptype for each record property.

Resource Record Object

Represents a resource record object.

{
  "id": "rsrcd_qx1w4ytagd8lf34",
  "resource_id": "resrc_vdcg9cycfn1u6t8",
  "resource_accessor": "custom.wishlist",
  "context_id": "wl_12345",
  "created_datetime": "2021-02-23T11:53:04.440756Z",
  "data": {
    "wishlist_id": "wl_12345",
    "wishlist_name": "Toy Collectibles"
  }
}

Attributes

Field Type Description
id string Unique identifier for the object.
resource_id string Unique identifier for resource.
resource_accessor string Accessor for resource.
context_id string ID of record based on context. For example, in the case of shopify.customer, this will be ID for Shopify Customer.
created_datetime string Datetime when record was created.
data object Data for record. Go to resources page to view list of available properties for record.

Retrieve Resource Record

Example Request

curl https://api.onvoard.com/v2/resource-records/rsrcd_qx1w4ytagd8lf34 \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "id": "rsrcd_qx1w4ytagd8lf34",
  "resource_id": "resrc_vdcg9cycfn1u6t8",
  "resource_accessor": "custom.wishlist",
  "context_id": "wl_12345",
  "created_datetime": "2021-02-23T11:53:04.440756Z",
  "data": {
    "wishlist_id": "wl_12345",
    "wishlist_name": "Toy Collectibles"
  }
}

Retrieve resource record with given ID.

HTTP Request

GET https://api.onvoard.com/v2/resource-records/:resource_record_id

Returns

Resource Record object if valid ID was provided.

Create Resource Record

You can only create record for resources with CUSTOM type and OBJECT kind.

Example Request

curl https://api.onvoard.com/v2/resource-records \
-X POST \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "resource": "resrc_vdcg9cycfn1u6t8",
  "context_id": "wl_12345",
  "data": {
    "wishlist_id": "wl_12345",
    "wishlist_name": "Toy Collectibles"
  }
}'

Example Response

{
  "id": "rsrcd_qx1w4ytagd8lf34",
  "resource_id": "resrc_vdcg9cycfn1u6t8",
  "resource_accessor": "custom.wishlist",
  "context_id": "wl_12345",
  "created_datetime": "2021-02-23T11:53:04.440756Z",
  "data": {
    "wishlist_id": "wl_12345",
    "wishlist_name": "Toy Collectibles"
  }
}

Create a new resource record.

HTTP Request

POST https://api.onvoard.com/v2/resource-records

Returns

Created resource record object if create succeeded.

Arguments

Field Type Required Description
resource string Yes ID of resource to associate with record.
context_id string Yes Unique identifier for record based on context.
data object No Data for record. Go to resources page to view list of available properties for record type.

Patch Resource Record

You can only patch record for resource with CUSTOM type and OBJECT kind.

Example Request

curl https://api.onvoard.com/v2/resource-records/rsrcd_qx1w4ytagd8lf34 \
-X PATCH \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "data": {
    "wishlist_id": "wl_12345",
    "wishlist_name": "Toys & Games"
  }
}'

Example Response

{
  "id": "rsrcd_qx1w4ytagd8lf34",
  "resource_id": "resrc_vdcg9cycfn1u6t8",
  "resource_accessor": "custom.wishlist",
  "context_id": "wl_12345",
  "created_datetime": "2021-02-23T11:53:04.440756Z",
  "data": {
    "wishlist_id": "wl_12345",
    "wishlist_name": "Toys & Games"
  }
}

Patch resource record object with given ID.

HTTP Request

PATCH https://api.onvoard.com/v2/resource-records/:resource_record_id

Returns

Modified resource record object object if patch succeeded.

Arguments

Field Type Required Description
data object No Data for record. Go to resources page to view list of available properties for record type.

Delete Resource Record

Example Request

curl https://api.onvoard.com/v2/resource-records/rsrcd_qx1w4ytagd8lf34 \
-X DELETE \
-H 'X-API-Key: {API_KEY}'

Example Response

{}

Delete resource record with given ID. You can only delete records from resource with EXTERNAL or CUSTOM type.

HTTP Request

DELETE https://api.onvoard.com/v2/resource-records/:resource_record_id

List all Resource Records

Example Request

curl https://api.onvoard.com/v2/resource-records \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "current_page": 1,
  "page_size": 10,
  "results": [{
    "id": "rsrcd_qx1w4ytagd8lf34",
    "resource_id": "resrc_vdcg9cycfn1u6t8",
    "resource_accessor": "custom.wishlist",
    "context_id": "wl_12345",
    "created_datetime": "2021-02-23T11:53:04.440756Z",
    "data": {
      "wishlist_id": "wl_12345",
      "wishlist_name": "Toys & Games"
    }
  }]
}

List all resource records user have access to. Records are sorted by created_datetime, starting from most recent records.

HTTP Request

GET https://api.onvoard.com/v2/resource-records

Returns

List of resource records objects.

Arguments

Field Type Description
id string Filter by id.
resource_id string Resource ID to filter. Use this to retrieve records from a specific resource.
resource_accessor string Resource Accessor to filter. Use this to retrieve records from a specific resource.
keyword string Filter by specific keyword.
context_id string Filter by context ID.
prop_key string Filter by property key. Must be used together with prop_value. For example, ?prop_key=product_id&prop_value=56789 to return records where product_id is 56789.
prop_value string Filter by property value. Must be used together with prop_key.
created_before integer Filter records created before provided timestamp.
created_after integer Filter records created after provided timestamp.
page integer Traverse to specific page. Page index starts from 1.
page_size integer Number of records you want to return for each page. Can be from 1 to 100. Default is 10.

Reviews

Review Object

Represents a review object.

{
  "id": "rvw_gg27c8bkm0v2a6u",
  "title": "Love this product",
  "content": "Would definitely buy it again",
  "rating": 5.0,
  "entity": "PRODUCT",
  "status": "PUBLISHED",
  "is_verified": false,
  "product": {
    "id": "prd_fraypsclbqclv8q",
    "external_id": "6304964542639",
    "name": "Ayres Chambray",
    "url": "https://onvoard-demo-site.myshopify.com/products/ayers-chambray",
    "image_url": "https://cdn.shopify.com/s/files/chambray_5f232530-492a-872c-81c225d6bafd.jpg"
  },
  "reviewer": {
    "id": "rvwer_y9ct5fd3ipobr9f",
    "contact": {
      "id": "ct_5a0af9v81k9xntm",
      "email": "john@example.com"
    },
    "display_name": "John Doe"
  },
  "num_upvotes": 0,
  "created_datetime": "2021-02-23T11:53:04.440756Z",
  "reply_datetime": null,
  "reply_html": "",
  "assets": []
}

Attributes

Field Type Description
id string Unique identifier for the object.
title string Title for review.
content string Content for review.
rating float Rating for review.
entity enum (Review Entity) Entity for review.
status enum (Review Status) Status for review.
is_verified boolean If review is verified. OnVoard will automatically mark a review as verified if reviewers' email address matches customer email address from your store's order records.
product object (Review Product Object) Product associated with review if entity is PRODUCT.
reviewer object (Reviewer Object) Reviewer information.
num_upvotes integer Number of upvotes for review.
created_datetime string Datetime when review was added to our system.
reply_datetime string Datetime when review was replied.
reply_html string HTML formatted string for review's reply.
assets[] object array (Asset Object) List of review assets.

Review Product Object

Represents a review product object. This is subset of main product object.

{
  "id": "prd_fraypsclbqclv8q",
  "external_id": "6304964542639",
  "name": "Ayres Chambray",
  "url": "https://onvoard-demo-site.myshopify.com/products/ayers-chambray",
  "image_url": "https://cdn.shopify.com/s/files/chambray_5f232530-492a-872c-81c225d6bafd.jpg"
}

Attributes

Field Type Description
id string Unique identifier for the object.
external_id string Unique identifier for product in ecommerce platform.
name string Name of product.
url string URL for product.
image_url string Image URL for product.

Reviewer Object

Represents a reviewer object.

{
  "id": "rvwer_y9ct5fd3ipobr9f",
  "contact": {
    "id": "ct_5a0af9v81k9xntm",
    "email": "john@example.com"
  },
  "display_name": "John Doe"
}

Attributes

Field Type Description
id string Unique identifier for the object.
contact object (Reviewer Contact Object) Contact associated with reviewer.
display_name string Display name for reviewer.

Reviewer Contact Object

Represents a reviewer contact object. This is subset of main contact object.

{
  "id": "ct_5a0af9v81k9xntm",
  "email": "john@example.com"
}

Attributes

Field Type Description
id string Unique identifier for the object.
email string Email of contact.

Asset Object

Represents a review asset object.

{
  "id": "m3g6wv7zdk5enff",
  "sort_order": 0,
  "image_media": {
    "id": "file_2qhvcjnbopus5ks",
    "file_url": "https://storage.googleapis.com/onvoard/upload/review/image-media/fbddba4a75163726d945.jpeg",
    "created_timestamp": 1593739557,
    "height": 1280,
    "width": 1920
  },
  "video_media": null
}

Attributes

Field Type Description
id string Unique identifier for the object.
sort_order integer Sort order for asset. Starts from 0.
image_media object (Image Media Object) Image for review. Either image_media or video_media will be set for each asset.
video_media object (Image Media Object) Video for review. Either image_media or video_media will be set for each asset.

Enums

List of available enum types under this resource.

Review Entity

Value Description
PRODUCT Product
SITE Site

Review Status

Value Description
PENDING Pending
PUBLISHED Published
UNPUBLISHED Unpublished

Retrieve Review

Example Request

curl https://api.onvoard.com/v2/reviews/ct_hws9idjxuiiui6r \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "id": "rvw_gg27c8bkm0v2a6u",
  "title": "Love this product",
  "content": "Would definitely buy it again",
  "rating": 5.0,
  "entity": "PRODUCT",
  "status": "PUBLISHED",
  "is_verified": false,
  "product": {
    "id": "prd_fraypsclbqclv8q",
    "external_id": "6304964542639",
    "name": "Ayres Chambray",
    "url": "https://onvoard-demo-site.myshopify.com/products/ayers-chambray",
    "image_url": "https://cdn.shopify.com/s/files/chambray_5f232530-492a-872c-81c225d6bafd.jpg"
  },
  "reviewer": {
    "id": "rvwer_y9ct5fd3ipobr9f",
    "contact": {
      "id": "ct_5a0af9v81k9xntm",
      "email": "john@example.com"
    },
    "display_name": "John Doe"
  },
  "num_upvotes": 0,
  "created_datetime": "2021-02-23T11:53:04.440756Z",
  "reply_datetime": null,
  "reply_html": "",
  "assets": []
}

Retrieve review with given ID.

HTTP Request

GET https://api.onvoard.com/v2/reviews/:review_id

Returns

Review object if valid ID was provided.

Create Review

Example Request

curl https://api.onvoard.com/v2/reviews \
-X POST \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "title": "Love this product",
  "content": "Would definitely buy it again soon if I can",
  "rating": 5.0,
  "entity": "PRODUCT",
  "status": "PUBLISHED",
  "reviewer_email": "john@example.com",
  "reviewer_display_name": "John Doe",
  "product_external_id": "6304964542639",
  "num_upvotes": 0,
  "image_urls": [
    "https://example.com/upload/review/image-media/111.jpeg?height=400",
    "https://example.com/upload/review/image-media/112.jpeg?height=400"
  ]
}'

Example Response

{
  "id": "rvw_vg6s09tu8f8wpiv",
  "title": "Love this product",
  "content": "Would definitely buy it again soon if I can",
  "rating": 5.0,
  "entity": "PRODUCT",
  "status": "PUBLISHED",
  "is_verified": false,
  "product": {
    "id": "prd_fraypsclbqclv8q",
    "external_id": "6304964542639",
    "name": "Ayres Chambray",
    "url": "https://onvoard-demo-site.myshopify.com/products/ayers-chambray",
    "image_url": "https://cdn.shopify.com/s/files/chambray_5f232530-492a-872c-81c225d6bafd.jpg"
  },
  "reviewer": {
    "id": "rvwer_wkv41dfvlgeu6vz",
    "contact": {
      "id": "ct_5a0af9v81k9xntm",
      "email": "john@example.com"
    },
    "display_name": "John Doe"
  },
  "num_upvotes": 0,
  "created_datetime": "2021-12-24T11:07:38.544222Z",
  "reply_datetime": null,
  "reply_html": "",
  "assets": [{
      "id": "m3dwg3vkvq78dra",
      "sort_order": 0,
      "image_media": {
        "id": "file_afgljt8awci9fuv",
        "file_url": "https://cdn.onvoard.com/upload/review/image-media/111.jpeg",
        "created_datetime": "2021-12-24T11:07:35.731490Z",
        "height": 400,
        "width": 300
      },
      "video_media": null
    },
    {
      "id": "a751okkhekze3f7",
      "sort_order": 1,
      "image_media": {
        "id": "file_ytrcuqbgy0axc35",
        "file_url": "https://cdn.onvoard.com/upload/review/image-media/112.jpeg",
        "created_datetime": "2021-12-24T11:07:37.038014Z",
        "height": 400,
        "width": 300
      },
      "video_media": null
    }
  ]
}

Create a new review.

HTTP Request

POST https://api.onvoard.com/v2/reviews

Returns

Created review object if create succeeded.

Arguments

Field Type Required Description
title string No Title for review.
content string Yes Content for review.
rating float Yes Rating for review. Should be between 1 to 5.
entity enum (Review Entity) Yes Entity for review.
status enum (Review Status) Yes Status for review.
reviewer_email string Yes Email for reviewer.
reviewer_display_name string Yes Display name for reviewer.
product_id string Maybe ID of product in OnVoard. If entity is PRODUCT, either product_id or product_external_id must be provided.
product_external_id string Maybe ID of product in ecommerce platform. If entity is PRODUCT, either product_id or product_external_id must be provided.
num_upvotes integer No Number of upvotes for review.
created_datetime string No Datetime when review was created. If left empty, we will use current datetime.
reply_datetime string No Datetime when review was replied.
reply_html string No HTML formatted string for review's reply.
image_urls[] string array No List of images for review.
video_urls[] string array No List of videos for review.

Patch Review

Example Request

curl https://api.onvoard.com/v2/reviews/rvw_rmkoqmzo8f511re \
-X PATCH \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "status": "PENDING"
}'

Example Response

{
  "id": "rvw_vg6s09tu8f8wpiv",
  "title": "Love this product",
  "content": "Would definitely buy it again soon if I can",
  "rating": 5.0,
  "entity": "PRODUCT",
  "status": "PENDING",
  "is_verified": false,
  "product": {
    "id": "prd_fraypsclbqclv8q",
    "external_id": "6304964542639",
    "name": "Ayres Chambray",
    "url": "https://onvoard-demo-site.myshopify.com/products/ayers-chambray",
    "image_url": "https://cdn.shopify.com/s/files/chambray_5f232530-492a-872c-81c225d6bafd.jpg"
  },
  "reviewer": {
    "id": "rvwer_wkv41dfvlgeu6vz",
    "contact": {
      "id": "ct_5a0af9v81k9xntm",
      "email": "john@example.com"
    },
    "display_name": "John Doe"
  },
  "num_upvotes": 0,
  "created_datetime": "2021-12-24T11:07:38.544222Z",
  "reply_datetime": null,
  "reply_html": "",
  "assets": [{
      "id": "m3dwg3vkvq78dra",
      "sort_order": 0,
      "image_media": {
        "id": "file_afgljt8awci9fuv",
        "file_url": "https://cdn.onvoard.com/upload/review/image-media/111.jpeg",
        "created_datetime": "2021-12-24T11:07:35.731490Z",
        "height": 400,
        "width": 300
      },
      "video_media": null
    },
    {
      "id": "a751okkhekze3f7",
      "sort_order": 1,
      "image_media": {
        "id": "file_ytrcuqbgy0axc35",
        "file_url": "https://cdn.onvoard.com/upload/review/image-media/112.jpeg",
        "created_datetime": "2021-12-24T11:07:37.038014Z",
        "height": 400,
        "width": 300
      },
      "video_media": null
    }
  ]
}

Patch review with given ID.

HTTP Request

PATCH https://api.onvoard.com/v2/reviews/:review_id

Returns

Modified review object if patch succeeded.

Arguments

Field Type Required Description
status enum (Review Status) No Status for this review.

Delete Review

Example Request

curl https://api.onvoard.com/v2/reviews/rvw_rmkoqmzo8f511re \
-X DELETE \
-H 'X-API-Key: {API_KEY}'

Example Response

{}

Delete review with given ID.

HTTP Request

DELETE https://api.onvoard.com/v2/reviews/:review_id

List all Reviews

Example Request

curl https://api.onvoard.com/v2/reviews \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "current_page": 1,
  "page_size": 10,
  "results": [{
    "id": "rvw_gg27c8bkm0v2a6u",
    "title": "Love this product",
    "content": "Would definitely buy it again",
    "rating": 5.0,
    "entity": "PRODUCT",
    "status": "PUBLISHED",
    "is_verified": false,
    "product": {
      "id": "prd_fraypsclbqclv8q",
      "external_id": "6304964542639",
      "name": "Ayres Chambray",
      "url": "https://onvoard-demo-site.myshopify.com/products/ayers-chambray",
      "image_url": "https://cdn.shopify.com/s/files/chambray_5f232530-492a-872c-81c225d6bafd.jpg"
    },
    "reviewer": {
      "id": "rvwer_y9ct5fd3ipobr9f",
      "contact": {
        "id": "ct_5a0af9v81k9xntm",
        "email": "john@example.com"
      },
      "display_name": "John Doe"
    },
    "num_upvotes": 0,
    "created_datetime": "2021-02-23T11:53:04.440756Z",
    "reply_datetime": null,
    "reply_html": "",
    "assets": []
  }]
}

List all reviews user have access to. Records are sorted by created_datetime, starting from most recent reviews.

HTTP Request

GET https://api.onvoard.com/v2/reviews

Returns

List of review objects.

Arguments

Field Type Description
id string Filter by id.
keyword string Filter by specific keyword.
entity enum (Review Entity) Filter by review entity.
status enum (Review Status) Filter by review status.
product_id string Product ID to filter.
product_external_id string Product External ID to filter.
product_group_id string Product Group ID to filter.
reviewer_email string Filter by reviewer email.
created_before integer Filter reviews created before provided timestamp.
created_after integer Filter reviews created after provided timestamp.
page integer Traverse to specific page. Page index starts from 1.
page_size integer Number of records you want to return for each page. Can be from 1 to 100. Default is 10.

Product Reviews Summaries

Product Reviews Summary Object

Represents a product reviews summary object.

{
  "product_id": "prd_1fyr0zgvtn3uvtl",
  "product_external_id": "4865006",
  "product_name": "Whitney Pullover",
  "last_reviewed_datetime": "2022-02-18T08:34:44.995921+00:00",
  "num_reviews": 1,
  "avg_rating": 4.0,
  "num_5_stars": 0,
  "num_4_stars": 1,
  "num_3_stars": 0,
  "num_2_stars": 0,
  "num_1_star": 0
}

Attributes

Field Type Description
product_id string OnVoard generated unique identifier for product.
product_external_id string Unique identifier for product in ecommerce platform.
product_name string Name of product.
last_reviewed_datetime string Datetime when product was last reviewed.
num_reviews integer Number of product reviews.
avg_rating float Average rating for product.
num_5_stars integer Number of 5-star reviews.
num_4_stars integer Number of 4-star reviews.
num_3_stars integer Number of 3-star reviews.
num_2_stars integer Number of 2-star reviews.
num_1_star integer Number of 1-star reviews.

List all Product Reviews Summaries

Example Request

curl https://api.onvoard.com/v2/product-reviews-summaries \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "current_page": 1,
  "page_size": 10,
  "results": [{
    "product_id": "prd_1fyr0zgvtn3uvtl",
    "product_external_id": "4865006",
    "product_name": "Whitney Pullover",
    "last_reviewed_datetime": "2022-02-18T08:34:44.995921+00:00",
    "num_reviews": 1,
    "avg_rating": 4.0,
    "num_5_stars": 0,
    "num_4_stars": 1,
    "num_3_stars": 0,
    "num_2_stars": 0,
    "num_1_star": 0
  }]
}

List all product reviews summaries. Records are sorted by most recently created product.

By default, we will get summary based on published reviews. For products that are assigned to groups, we generate summary based on assigned product group.

HTTP Request

GET https://api.onvoard.com/v2/product-reviews-summaries

Returns

List of review objects.

Arguments

Field Type Description
product_id string Product ID to filter.
product_external_id string Product External ID to filter.
product_group_id string Product Group ID to filter.
use_group boolean Whether we should use product group summary when product is assigned to group. Use true or false to filter. This is true by default.
published_only boolean Whether we should only use reviews that are published. Use true or false to filter. This is true by default. If false, we will use all product reviews, including pending and unpublished.
page integer Traverse to specific page. Page index starts from 1.
page_size integer Number of records you want to return for each page. Can be from 1 to 100. Default is 10.

Webhooks

You can setup webhooks to get notified for the following events.

A few things to know about webhooks.

See webhook payloads for sample payloads for each event.

Webhook Object

Represents a webhook object.

{
  "id": "wh_ji705uh2d48gf0d",
  "active": true,
  "url": "https://hookb.in/Z2JkyQlzV7iK6bmm6m21",
  "event_types": [
    "contact.saved"
  ]
}

Attributes

Field Type Description
id string Unique identifier for the object.
active boolean If webhook is currently active.
url string URL of webhook to post request.
event_types[] enum array (Webhook Event Type) Array of event types to subscribe.

Enums

List of available enum types under this resource.

Webhook Event Type

Value Description
contact.created When contact is created.
contact.saved When contact is created or updated.
review.created When review is created.
back_in_stock_subscriber.saved When back-in-stock subscriber is created or updated. Update occurs when a user subscribes to the same product. We're tracking updates since subscribed variants may changed.
back_in_stock_notification.created When back-in-stock notification is generated.
prompt_response.created When prompt response is created. This will fire on first page form submission.
prompt_response.saved When prompt response is created or updated. Use this if prompt has multiple pages of forms.

Retrieve Webhook

Example Request

curl https://api.onvoard.com/v2/webhooks/wh_ji705uh2d48gf0d \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "id": "wh_ji705uh2d48gf0d",
  "active": true,
  "url": "https://hookb.in/Z2JkyQlzV7iK6bmm6m21",
  "event_types": [
    "contact.saved"
  ]
}

Retrieve webhook with given ID.

HTTP Request

GET https://api.onvoard.com/v2/webhooks/:webhook_id

Returns

Webhook object if valid ID was provided.

Create Webhook

Example Request

curl https://api.onvoard.com/v2/webhooks \
-X POST \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "active": true,
  "url": "https://example.com/abc",
  "event_types": [
    "contact.saved"
  ]
}'

Example Response

{
  "id": "wh_vn2df64iul097cm",
  "active": true,
  "url": "https://example.com/abc",
  "event_types": [
    "contact.saved"
  ]
}

Create a new webhook.

HTTP Request

POST https://api.onvoard.com/v2/webhooks

Returns

Created webhook object if create succeeded.

Arguments

Field Type Required Description
url string Yes URL of webhook to post request.
event_types[] enum array (Webhook Event Type Yes Array of event types to subscribe.
active boolean No Default value is true.
secret string No If you provide a secret, we will add X-Hub-Signature HTTP header to call webhook url. This signature is generated with SHA1 using provided secret and request body. To validate request, compute expected signature on your end and compare it with X-Hub-Signature. Keep in mind that for security reasons, we do not show secret when returning webhook object. If you need to check, you can go to webhooks page.

Patch Webhook

Example Request

curl https://api.onvoard.com/v2/webhooks/ct_573taa9z5yd1iv7 \
-X PATCH \
-H 'X-API-Key: {API_KEY}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "active": false,
}'

Example Response

{
  "id": "wh_vn2df64iul097cm",
  "active": false,
  "url": "https://example.com/abc",
  "event_types": [
    "contact.saved"
  ]
}

Patch webhook with given ID.

HTTP Request

PATCH https://api.onvoard.com/v2/webhooks/:webhook_id

Returns

Modified webhook object if patch succeeded.

Arguments

Field Type Required Description
url string No URL of webhook to post request.
event_types[] enum array (Webhook Event Type No Array of event types to subscribe.
active boolean No Inactive webhooks won't trigger callbacks.
secret string No If you provide a secret, we will add X-Hub-Signature HTTP header to call webhook url. This signature is generated with SHA1 using provided secret and request body. To validate request, compute expected signature on your end and compare it with X-Hub-Signature. Keep in mind that for security reasons, we do not show secret when returning webhook object. If you need to check, you can go to webhooks page.

Delete Webhook

Example Request

curl https://api.onvoard.com/v2/webhooks/wh_vn2df64iul097cm \
-X DELETE \
-H 'X-API-Key: {API_KEY}'

Example Response

{}

Delete webhook with given ID.

HTTP Request

DELETE https://api.onvoard.com/v2/webhooks/:webhook_id

List all Webhooks

Example Request

curl https://api.onvoard.com/v2/webhooks \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "current_page": 1,
  "page_size": 10,
  "results": [{
    "id": "wh_ji705uh2d48gf0d",
    "active": true,
    "url": "https://hookb.in/Z2JkyQlzV7iK6bmm6m21",
    "event_types": [
      "contact.saved"
    ]
  }]
}

List all webhooks user have access to.

HTTP Request

GET https://api.onvoard.com/v2/webhooks

Returns

List of webhook objects.

Arguments

Field Type Description
id string Filter by id.
keyword string Filter by specific keyword.
active boolean Use true or false to filter.
event_types string Comma-seperated list of event types to filter with. For example, contact.created,contact.saved.
page integer Traverse to specific page. Page index starts from 1.
page_size integer Number of records you want to return for each page. Can be from 1 to 100. Default is 10.

Data Types

Various data types used for API endpoints.

Image Media Object

Object for representing image media.

{
  "id": "file_b027hj4e3483rhi",
  "file_url": "https://storage.googleapis.com/onvoard/upload/product/image-media/4dc8b25e1275d2836b7b.jpeg",
  "created_datetime": "2021-08-12T23:09:54.588927Z",
  "height": 1280,
  "width": 1920
}

Attributes

Field Type Description
id string Unique identifier for the object.
file_url string Url to view image.
height integer Height dimension of image.
width integer Width dimension of image.
created_datetime string Created datetime of image.

Video Media Object

Object for representing video media.

{
  "id": "file_b027hj4e3483rhi",
  "file_url": "https://storage.googleapis.com/onvoard/upload/review/video-media/4dc8b25e1275d2836b7b.mp4",
  "thumbnail_url": "https://storage.googleapis.com/onvoard/upload/review/video-thumbnail-media/4dc8b25e1275d2836b7b.png",
  "thumbnail_height": 1280,
  "thumbnail_width": 1920,
  "created_datetime": "2021-08-12T23:09:54.588927Z"
}

Attributes

Field Type Description
id string Unique identifier for the object.
file_url string Url to view video.
thumbnail_url string Url to view video thumbnail.
thumbnail_height integer Height dimension of video thumbnail.
thumbnail_width integer Width dimension of video thumbnail.
created_datetime string Created datetime of video.

Enums

Various enums used for API endpoints.

Property Field Type

Value Description
TEXT Text input field. Value type will be STRING.
MULTI_LINE_TEXT Multi-line text field. Value type will be STRING.
NUMBER Numeric field. Value type will be NUMBER.
EMAIL Email field. Will validate to ensure valid email. Value type will be STRING.
PHONE Phone field. Will validate and format value to ensure valid phone number. Value type will be STRING.
URL Url field. Will validate and format value to ensure valid url. Value type will be STRING.
COUNTRY Alpha-2 country field like US, CA. Will validate to ensure valid country alpha-2 code. Value type will be STRING.
CURRENCY Three-letter currency code (ISO 4217 format) like USD, CAD. Will validate to ensure valid currency code. Value type will be STRING.
TIMEZONE Timezone field. Will validate to ensure valid timezone. Value type will be STRING.
DATE Date field. Will store data as unix timestamp. Value type will be DATETIME.
DATETIME Datetime field. Will store data as unix timestamp. Value type will be DATETIME.
SWITCH ON/OFF switch field. Value type will be BOOLEAN.
BOOLEAN_SELECT Select field with true and false option. Value type will be BOOLEAN.
SINGLE_SELECT Single select field with options. Value type will be STRING.
MULTI_SELECT Multi-select field with options. Value type will be STRING_ARRAY.
TAGS Tag-select field with options. Value type will be STRING_ARRAY.
SINGLE_LINE_ITEM Nested object. This is used interally by OnVoard. Currently, we do not support adding new property type with SINGLE_LINE_ITEM field type. Value type will be OBJECT.
MULTIPLE_LINE_ITEMS Multiple nested objects. This is used interally by OnVoard. Currently, we do not support adding new property type with MULTIPLE_LINE_ITEMS field type. Value type will be OBJECT_ARRAY.

Property Value Type

Value Description
STRING String value.
STRING_ARRAY String array value. Commonly used for tags.
NUMBER Number value. Will store as float.
DATETIME Datetime value. Will store as epoch timestamp.
BOOLEAN Boolean value.
DICT Dictionary similar to associative array in key-value pairs. For example {"first_name": "John", "last_name": "Doe"}.
OBJECT Similar to DICT but will be stored as line item with specified property types. The key difference compared to dict is that we can evaluate each nested property for object. Currently, we do not support adding new property type with OBJECT value type.
OBJECT_ARRAY List of objects. Currently, we do not support adding new property type with OBJECT_ARRAY value type.

Webhook Payloads

Below are payload examples for webhook events.

contact.created

Example Payload

{
  "id": "evt_gd5yjx39li2bkjh09kiv",
  "type": "contact.created",
  "created_datetime": "2021-12-23T03:40:40.495545Z",
  "data": {
    "contact": {
      "id": "ct_qauejq13aixtowf",
      "name": "Jane Doe",
      "tags": [
        "Premium"
      ],
      "email": "jane@example.com",
      "phone": "",
      "last_name": "Doe",
      "first_name": "Jane",
      "suppressed": false,
      "email_sendable": true,
      "created_datetime": 1640234661,
      "email_hard_bounced": false,
      "email_unsubscribed": false,
      "suppressed_datetime": null,
      "email_marked_as_spam": false,
      "email_double_opted_in": false,
      "accepts_marketing_emails": false,
      "email_soft_bounced_count": 0,
      "email_double_optin_status": "NOT_SET"
    }
  }
}

When contact is created.

contact.saved

Example Payload

{
  "id": "evt_gd5yjx39li2bkjh09kiv",
  "type": "contact.saved",
  "created_datetime": "2021-12-23T03:40:40.495545Z",
  "data": {
    "contact": {
      "id": "ct_qauejq13aixtowf",
      "name": "Jane Doe",
      "tags": [
        "Premium"
      ],
      "email": "jane@example.com",
      "phone": "",
      "last_name": "Doe",
      "first_name": "Jane",
      "suppressed": false,
      "email_sendable": true,
      "created_datetime": 1640234661,
      "email_hard_bounced": false,
      "email_unsubscribed": false,
      "suppressed_datetime": null,
      "email_marked_as_spam": false,
      "email_double_opted_in": false,
      "accepts_marketing_emails": false,
      "email_soft_bounced_count": 0,
      "email_double_optin_status": "NOT_SET"
    }
  }
}

When contact is created or updated.

review.created

Example Payload

{
  "id": "evt_gd5yjx39li2bkjh09kiv",
  "type": "review.created",
  "created_datetime": "2021-12-23T03:40:40.495545Z",
  "data": {
    "review": {
      "id": "rvw_wxw1jm8xi4yub0n",
      "title": "Love this product",
      "assets": [{
        "id": "tk5b6k51rhxry2r",
        "image_url": "https://storage.googleapis.com/onvoard/upload/review/image-media/ed9be6cc19dd29b37c8bcd.jpeg",
        "video_url": null,
        "video_thumbnail_url": null
      }],
      "entity": "PRODUCT",
      "rating": 5,
      "status": "PUBLISHED",
      "content": "Would definitely buy it again soon if I can",
      "reviewer": {
        "email": "john@example.com",
        "display_name": "John Doe"
      },
      "product_id": "prd_fraypsclbqclv8q",
      "reply_html": null,
      "reply_datetime": null,
      "created_datetime": 1640345275
    }
  }
}

When review is created.

back_in_stock_subscriber.saved

Example Payload

{
  "id": "evt_gd5yjx39li2bkjh09kiv",
  "type": "back_in_stock_subscriber.saved",
  "created_datetime": "2021-12-23T03:40:40.495545Z",
  "data": {
    "back_in_stock_subscribed": {
      "contact_id": "ct_b95esyy0ez6twst",
      "activity_id": "ctact_t48uhysef4mgj8ae5p3j",
      "variant_ids": [
        "38309178933423",
        "38309178998959"
      ],
      "contact_email": "john553@example.com",
      "product_title": "Guaranteed",
      "activity_datetime": 1624380419,
      "inventory_item_keys": [
        "6304965066927:38309178933423",
        "6304965066927:38309178998959"
      ],
      "product_external_id": "6304965066927",
      "notification_generated": true
    }
  }
}

When back-in-stock subscriber is created or updated. Update occurs when a user subscribes to the same product. We're tracking updates since subscribed variants may changed.

back_in_stock_notification.created

Example Payload

{
  "id": "evt_gd5yjx39li2bkjh09kiv",
  "type": "back_in_stock_notification.created",
  "created_datetime": "2021-12-23T03:40:40.495545Z",
  "data": {
    "back_in_stock_notification": {
      "contact_id": "ct_b95esyy0ez6twst",
      "variant_id": "38309178933423",
      "activity_id": "ctact_pstwb0mvgyn9gp3xqau8",
      "product_url": "https://onvoard-demo-store.myshopify.com/products/guaranteed",
      "contact_email": "john553@example.com",
      "product_title": "Guaranteed",
      "variant_title": "Navy / XS",
      "activity_datetime": 1624380486,
      "product_image_url": "https://cdn.shopify.com/s/files/1/0266/3704/1712/products/guaranteed_navy.jpg?v=1613276755",
      "email_recipient_id": "erpt_xr0s49y7f1flm07",
      "inventory_item_key": "6304965066927:38309178933423",
      "product_full_title": "Guaranteed [Navy / XS]",
      "product_external_id": "6304965066927",
      "subscribed_datetime": 1624380419,
      "subscribed_activity_id": "ctact_t48uhysef4mgj8ae5p3j"
    }
  }
}

When back-in-stock notification is generated.

prompt_response.created

Example Payload

{
  "id": "evt_gd5yjx39li2bkjh09kiv",
  "type": "prompt_response.created",
  "created_datetime": "2021-12-23T03:40:40.495545Z",
  "data": {
    "prompt_response": {
      "id": "pmtresp_q6tvy767v1vb8ig",
      "prompt_id": "pmt_0bzbvyeg49aazns",
      "prompt_name": "Lead Capture",
      "created_datetime": "2021-12-23T03:40:40.495545Z",
      "modified_datetime": "2021-12-23T03:40:40.551498Z",
      "data": {
        "name": "John Doe",
        "email": "john@example.com",
        "phone": ""
      }
    }
  }
}

When prompt response is created. This will fire on first page form submission.

prompt_response.saved

Example Payload

{
  "id": "evt_gd5yjx39li2bkjh09kiv",
  "type": "prompt_response.saved",
  "created_datetime": "2021-12-23T03:40:40.495545Z",
  "data": {
    "prompt_response": {
      "id": "pmtresp_q6tvy767v1vb8ig",
      "prompt_id": "pmt_0bzbvyeg49aazns",
      "prompt_name": "Lead Capture",
      "created_datetime": "2021-12-23T03:40:40.495545Z",
      "modified_datetime": "2021-12-23T03:40:40.551498Z",
      "data": {
        "name": "John Doe",
        "email": "john@example.com",
        "phone": ""
      }
    }
  }
}

When prompt response is created or updated. Use this if prompt has multiple pages of forms.

shell