NAV Navbar
shell

Introduction

You can use OnVoard's API to access various endpoints, and perform tasks in programmatic fashion such as sending email surveys via triggers. Currently, the key use cases supported by OnVoard's API are:

Authentication

# Api calls must be made with token header
curl 'https://api.onvoard.com/v1/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/v1/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.

Accounts

Represents a account object.

Account Object

{
  "id": "acct_u4o2a8hmqk5rzp9",
  "name": "Starbucks",
  "organization": {
    "id": "org_xf041wyn93dd8uc",
    "name": "OnVoard"
  }
}

Attributes

Field Type Description
id string Unique identifier for the object.
name string Name of account.
organization.id string Unique identifier for organization.
organization.name string Name of organization.

Retrieve Account

Example Request

curl 'https://api.onvoard.com/v1/accounts/acct_u4o2a8hmqk5rzp9' \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "id": "acct_u4o2a8hmqk5rzp9",
  "name": "Starbucks",
  "organization": {
    "id": "org_xf041wyn93dd8uc",
    "name": "OnVoard"
  }
}

Retrieve account with given ID.

HTTP Request

GET https://api.onvoard.com/v1/accounts/:account_id

Returns

Account object if valid ID was provided.

List all Accounts

Example Request

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

Example Response

{
  "num_records": 1,
  "num_pages": 1,
  "current_page": 1,
  "results": [{
    "id": "acct_u4o2a8hmqk5rzp9",
    "name": "Starbucks",
    "organization": {
      "id": "org_xf041wyn93dd8uc",
      "name": "OnVoard"
    }
  }]
}

List all accounts user has access to.

HTTP Request

GET https://api.onvoard.com/v1/accounts

Returns

List of account objects.

Arguments

Field Type Description
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

Represents a review object. Reviews can be collected from various sources like google and facebook.

Review Object

{
  "id": "rvw_7vomjp0vjokbq09",
  "active": true,
  "review_listing": {
    "id": "rwl_1igyg8wuxd5jiil",
    "name": "Carousell Google Play"
  },
  "status": "PENDING",
  "recommend": null,
  "rating": 5.0,
  "title": "Thank you, Carousell",
  "content": "I absolutely love this app!",
  "url": "",
  "source_review_id": "3465825614",
  "review_date": "2018-11-27",
  "reviewer_name": "Rodristar",
  "reviewer_pic_url": "",
  "reply_text": "",
  "reply_date": null,
  "attributes": [{
    "name": "App Version",
    "value": "2.91.0"
  }],
  "score": "THREE",
  "source": {
    "id": "appstore",
    "name": "iOS App Store"
  },
  "created_timestamp": 1543414453
}

Attributes

Field Type Description
id string Unique identifier for the object.
active boolean Active state of review. Filtered reviews will return false.
review_listing.id string Unique identifier of review listing.
review_listing.name string Name of review listing.
status enum (Review Status) Status of this review.
recommend boolean Recommend score for reviewed item. Field will be null if binary rating system is not used.
rating float Rating score for reviewed item. Field will be null if 5-star rating system is not used.
title string Title of review.
content string Content of review.
url string Url to review.
source_review_id string Review's unique identifier in source's context.
review_date string Date of review. ISO 8601 format, YYYY-MM-DD.
reviewer_name string Reviewer's name.
reviewer_pic_url string Reviewer's pic url.
reply_text string Replied text.
reply_date string Replied date. ISO 8601 format, YYYY-MM-DD.
attributes[].name string Name for review's attribute.
attributes[].value string Value for review's attribute.
score enum (Review Score) Score for this review.
source.id string Unique identifier of linked source.
source.name string Name of linked source.
created_timestamp integer Timestamp when review was added to our system.

Enums

List of available enum types under this resource.

Review Status

Value Description
PENDING Pending Response
RESPONDED Responded
SKIP Skip Response

Review Score

Value Description
NA No Scores
ZERO 0 Star Range
ONE 1 Star Range
TWO 2 Star Range
THREE 3 Star Range
FOUR 4 Star Range
FIVE 5 Star Range
POSITIVE Recommend
NEGATIVE Doesn't Recommend

Retrieve Review

Example Request

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

Example Response

{
  "id": "rvw_7vomjp0vjokbq09",
  "active": true,
  "review_listing": {
    "id": "rwl_1igyg8wuxd5jiil",
    "name": "Carousell Google Play"
  },
  "status": "PENDING",
  "recommend": null,
  "rating": 5.0,
  "title": "Thank you, Carousell",
  "content": "I absolutely love this app!",
  "url": "",
  "source_review_id": "3465825614",
  "review_date": "2018-11-27",
  "reviewer_name": "Rodristar",
  "reviewer_pic_url": "",
  "reply_text": "",
  "reply_date": null,
  "attributes": [{
    "name": "App Version",
    "value": "2.91.0"
  }],
  "score": "THREE",
  "source": {
    "id": "appstore",
    "name": "iOS App Store"
  },
  "created_timestamp": 1543414453
}

Retrieve review with given ID.

HTTP Request

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

Returns

Review object if valid ID was provided.

Patch Review

Example Request

curl 'https://api.onvoard.com/v1/reviews/rvw_7vomjp0vjokbq09' \
-H 'X-API-Key: {API_KEY}'
-d status="RESPONDED"

Example Response

{
  "id": "rvw_7vomjp0vjokbq09",
  "active": true,
  "review_listing": {
    "id": "rwl_1igyg8wuxd5jiil",
    "name": "Carousell Google Play"
  },
  "status": "RESPONDED",
  "recommend": null,
  "rating": 5.0,
  "title": "Thank you, Carousell",
  "content": "I absolutely love this app!",
  "url": "",
  "source_review_id": "3465825614",
  "review_date": "2018-11-27",
  "reviewer_name": "Rodristar",
  "reviewer_pic_url": "",
  "reply_text": "",
  "reply_date": null,
  "attributes": [{
    "name": "App Version",
    "value": "2.91.0"
  }],
  "score": "THREE",
  "source": {
    "id": "appstore",
    "name": "iOS App Store"
  },
  "created_timestamp": 1543414453
}

Patch review with given ID.

HTTP Request

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

Returns

Modified review object if patch succeeded.

Arguments

Field Type Required Description
active boolean No Active state of review.
status enum (Review Status) No Status of review.

List all Reviews

Example Request

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

Example Response

{
  "num_records": 1,
  "num_pages": 1,
  "current_page": 1,
  "results": [{
    "id": "rvw_7vomjp0vjokbq09",
    "active": true,
    "review_listing": {
      "id": "rwl_1igyg8wuxd5jiil",
      "name": "Carousell Google Play"
    },
    "status": "RESPONDED",
    "recommend": null,
    "rating": 5.0,
    "title": "Thank you, Carousell",
    "content": "I absolutely love this app!",
    "url": "",
    "source_review_id": "3465825614",
    "review_date": "2018-11-27",
    "reviewer_name": "Rodristar",
    "reviewer_pic_url": "",
    "reply_text": "",
    "reply_date": null,
    "attributes": [{
      "name": "App Version",
      "value": "2.91.0"
    }],
    "score": "THREE",
    "source": {
      "id": "appstore",
      "name": "iOS App Store"
    },
    "created_timestamp": 1543414453
  }]
}

List all reviews user has access to.

HTTP Request

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

Returns

List of review objects.

Arguments

Field Type Description
active boolean Use true if you only want to return unfiltered reviews and false to return filtered reviews.
status enum (Review Status) Filter by review status.
keyword string Filter by specific keyword.
account string Account ID to filter. Used when organization manage more than one account.
scores string Comma-seperated list of scores to filter with. See Review Score.
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.

Review Requesters

Represents a review requester object. Can be used to send review request via email.

Review Requester Object

{
  "id": "rwreq_awxloccld94xkfh",
  "name": "OnVoard G2",
  "type": "SINGLE_SITE",
  "active": true,
  "tracking_on": true,
  "dedup_window": 100
}

Attributes

Field Type Description
id string Unique identifier for the object.
name string Name for review requester.
type enum (Review Requester Type) Type for this review requester.
active boolean Active state of review requester. Archived review requester will be false.
tracking_on boolean Will be true if tracking is turned on.
dedup_window integer Number of days to lookback and deduplicate so you can avoid sending review requests to the same email.

Enums

List of available enum types under this resource.

Review Requester Type

Value Description
SINGLE_SITE Request reviews for a specific site. This can be incentivized with rewards.
MULTIPLE_SITES Request reviews by showcasing a list of sites users can leave reviews on. This can't be incentivized with rewards.

Retrieve Review Requester

Example Request

curl 'https://api.onvoard.com/v1/review-requesters/rwreq_awxloccld94xkfh' \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "id": "rwreq_awxloccld94xkfh",
  "name": "OnVoard G2",
  "type": "SINGLE_SITE",
  "active": true,
  "tracking_on": true,
  "dedup_window": 100
}

Retrieve review requester with given ID.

HTTP Request

GET https://api.onvoard.com/v1/review-requesters/:review_requester_id

Returns

Review requester object if valid ID was provided.

Patch Review Requester

Example Request

curl 'https://api.onvoard.com/v1/review-requesters/rwreq_awxloccld94xkfh' \
-H 'X-API-Key: {API_KEY}'
-d active=false

Example Response

{
  "id": "rwreq_awxloccld94xkfh",
  "name": "OnVoard G2",
  "type": "SINGLE_SITE",
  "active": false,
  "tracking_on": true,
  "dedup_window": 100
}

Patch review requester with given ID.

HTTP Request

PATCH https://api.onvoard.com/v1/review-requesters/:review_requester_id

Returns

Modified review requester object if patch succeeded.

Arguments

Field Type Required Description
active boolean No Active state of review requester.

Send Review Request

Example Request

curl 'https://api.onvoard.com/v1/review-requesters/rwreq_awxloccld94xkfh/send' \
-H 'X-API-Key: {API_KEY}'
-d name="John Doe" \
-d email="johndoe@gmail.com"

Example Response

{
  "id": "rrrpt_3e6mz1ur0aoycy8v7jsj8aekw",
  "tracking_id": "r6kMe3QwGjE0pilgCk7Q",
  "test": false,
  "name": "John Doe",
  "email": "johndoe@gmail.com",
  "lag_window": null,
  "status": "NA",
  "sent_from": "CONSOLE",
  "error_msg": "",
  "created_timestamp": 1560229938,
  "reminder": {
    "status": "NA",
    "error_msg": ""
  },
  "activities": [{
    "id": "ldact_1v48gdzek5tshgbxflaoly97tx46kz",
    "type": "SENT_REVIEW_REQUEST",
    "created_timestamp": 1560158564
  }],
  "requester": {
    "id": "rwreq_awxloccld94xkfh",
    "name": "OnVoard G2"
  }
}

Send review request with given ID.

HTTP Request

POST https://api.onvoard.com/v1/review-requesters/:review_requester_id/send

Returns

Review Requester Recipient Object if review request was sent.

Arguments

Field Type Required Description
email string Yes Email address to send.
name string No Name of recipient. We will automatically extract first and last name.
lag_window integer No Send review request after indicated number of minutes. If specified, lag window must be between 10 and 10080 (7 days).

List all Review Requesters

Example Request

curl 'https://api.onvoard.com/v1/review-requesters' \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "num_records": 1,
  "num_pages": 1,
  "current_page": 1,
  "results": [{
    "id": "rwreq_awxloccld94xkfh",
    "name": "OnVoard G2",
    "type": "SINGLE_SITE",
    "active": true,
    "tracking_on": true,
    "dedup_window": 100
  }]
}

List all review requesters user has access to.

HTTP Request

GET https://api.onvoard.com/v1/review-requests

Returns

List of review request objects.

Arguments

Field Type Description
active boolean Use true if you only want to return active review requesters and false to return archived review requests.
tracking_on boolean Filter by tracking status.
type enum (Reviewer Requester Type) Filter by review requester type.
keyword string Filter by specific keyword.
account string Account ID to filter. Used when organization manage more than one account.
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.

Incentivized Reviewers

Represents an incentivized reviewer object. Incentivized reviewer is created when recipient applies for rewards. recipient.id is unique identifier for object.

Incentivized Reviewer Object

{
  "recipient": {
    "id": "rrrpt_gnnixeln0g5j4qaexgru4vnlo",
    "tracking_id": "6jYSgafXNU78AFaPzhSt",
    "test": false,
    "name": "",
    "email": "johndoe@gmail.com",
    "lag_window": null,
    "status": "DELIVERED",
    "sent_from": "CONSOLE",
    "error_msg": "",
    "created_timestamp": 1560258949,
    "reminder": {
      "status": "NA",
      "error_msg": ""
    },
    "activities": [{
        "id": "ldact_tjmz6hsha8qrpfyeogi5neupshfkr4",
        "type": "SENT_REVIEW_REQUEST",
        "created_timestamp": 1560258949
      },
      {
        "id": "ldact_hk8d1et2o5upw2rgqexej2jerpip0s",
        "type": "DELIVERED_REVIEW_REQUEST",
        "created_timestamp": 1560258949
      },
      {
        "id": "ldact_j9we8sristm96dgkkfi0y01yqdr5zm",
        "type": "CLICKED_REVIEW_REQUEST",
        "created_timestamp": 1560258957
      },
      {
        "id": "ldact_k1sxut7xm7tx7k1jxomwhrjb4cg09z",
        "type": "REQUESTED_REVIEW_REWARDS",
        "created_timestamp": 1560259060
      }
    ],
    "requester": {
      "id": "rwreq_awxloccld94xkfh",
      "name": "OnVoard G2"
    }
  },
  "reward": {
    "id": "rwd_4xg0gauv5x6n2ag",
    "desc": "All specified requirements must be fulfilled",
    "fulfillment_mode": "MANUAL",
    "footnote": "It takes around 7 days for rewards to be delivered",
    "line_items": [{
      "id": "8d14t84kcvupxqj",
      "label": "$10 Amazon Gift Card",
      "requested": true
    }],
    "custom_fields": [{
      "id": "zzvqi0ygechgacj",
      "name": "Email",
      "desc": "Your email to receive gift card",
      "type": "EMAIL",
      "value": "johnd66@gmail.com"
    }]
  },
  "status": "PENDING",
  "created_timestamp": 1560259060
}

Attributes

Field Type Description
recipient object (Review Requester Recipient Object) Recipient linked to incentivized reviewer. This is also the parent object.
reward object (Reward Object) Reward attached to incentivized reviewer.
status enum (Incentivized Reviewer Status) Status for incentivized reviewer.
created_timestamp integer Timestamp when incentivized reviewer is created.

Enums

List of available enum types under this resource.

Incentivized Reviewer Status

Value Description
VOID Void
PENDING Pending. This is the default status.
FOLLOWUP Follow-up
APPROVED Approved

Retrieve Incentivized Reviewer

Example Request

curl 'https://api.onvoard.com/v1/incentivized-reviewers/rrrpt_gnnixeln0g5j4qaexgru4vnlo' \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "recipient": {
    "id": "rrrpt_gnnixeln0g5j4qaexgru4vnlo",
    "tracking_id": "6jYSgafXNU78AFaPzhSt",
    "test": false,
    "name": "",
    "email": "johndoe@gmail.com",
    "lag_window": null,
    "status": "DELIVERED",
    "sent_from": "CONSOLE",
    "error_msg": "",
    "created_timestamp": 1560258949,
    "reminder": {
      "status": "NA",
      "error_msg": ""
    },
    "activities": [{
        "id": "ldact_tjmz6hsha8qrpfyeogi5neupshfkr4",
        "type": "SENT_REVIEW_REQUEST",
        "created_timestamp": 1560258949
      },
      {
        "id": "ldact_hk8d1et2o5upw2rgqexej2jerpip0s",
        "type": "DELIVERED_REVIEW_REQUEST",
        "created_timestamp": 1560258949
      },
      {
        "id": "ldact_j9we8sristm96dgkkfi0y01yqdr5zm",
        "type": "CLICKED_REVIEW_REQUEST",
        "created_timestamp": 1560258957
      },
      {
        "id": "ldact_k1sxut7xm7tx7k1jxomwhrjb4cg09z",
        "type": "REQUESTED_REVIEW_REWARDS",
        "created_timestamp": 1560259060
      }
    ],
    "requester": {
      "id": "rwreq_awxloccld94xkfh",
      "name": "OnVoard G2"
    }
  },
  "reward": {
    "id": "rwd_4xg0gauv5x6n2ag",
    "desc": "All specified requirements must be fulfilled",
    "fulfillment_mode": "MANUAL",
    "footnote": "It takes around 7 days for rewards to be delivered",
    "line_items": [{
      "id": "8d14t84kcvupxqj",
      "label": "$10 Amazon Gift Card",
      "requested": true
    }],
    "custom_fields": [{
      "id": "zzvqi0ygechgacj",
      "name": "Email",
      "desc": "Your email to receive gift card",
      "type": "EMAIL",
      "value": "johnd66@gmail.com"
    }]
  },
  "status": "PENDING",
  "created_timestamp": 1560259060
}

Retrieve incentivized reviewer with recipient ID.

HTTP Request

GET https://api.onvoard.com/v1/incentivized-reviewers/:recipient_id

Returns

Incentivized reviewer object if valid recipient ID was provided.

Patch Incentivized Reviewer

Example Request

curl 'https://api.onvoard.com/v1/incentivized-reviewers/rrrpt_gnnixeln0g5j4qaexgru4vnlo' \
-H 'X-API-Key: {API_KEY}'
-d status="FOLLOWUP"

Example Response

{
  "recipient": {
    "id": "rrrpt_gnnixeln0g5j4qaexgru4vnlo",
    "tracking_id": "6jYSgafXNU78AFaPzhSt",
    "test": false,
    "name": "",
    "email": "johndoe@gmail.com",
    "lag_window": null,
    "status": "DELIVERED",
    "sent_from": "CONSOLE",
    "error_msg": "",
    "created_timestamp": 1560258949,
    "reminder": {
      "status": "NA",
      "error_msg": ""
    },
    "activities": [{
        "id": "ldact_tjmz6hsha8qrpfyeogi5neupshfkr4",
        "type": "SENT_REVIEW_REQUEST",
        "created_timestamp": 1560258949
      },
      {
        "id": "ldact_hk8d1et2o5upw2rgqexej2jerpip0s",
        "type": "DELIVERED_REVIEW_REQUEST",
        "created_timestamp": 1560258949
      },
      {
        "id": "ldact_j9we8sristm96dgkkfi0y01yqdr5zm",
        "type": "CLICKED_REVIEW_REQUEST",
        "created_timestamp": 1560258957
      },
      {
        "id": "ldact_k1sxut7xm7tx7k1jxomwhrjb4cg09z",
        "type": "REQUESTED_REVIEW_REWARDS",
        "created_timestamp": 1560259060
      }
    ],
    "requester": {
      "id": "rwreq_awxloccld94xkfh",
      "name": "OnVoard G2"
    }
  },
  "reward": {
    "id": "rwd_4xg0gauv5x6n2ag",
    "desc": "All specified requirements must be fulfilled",
    "fulfillment_mode": "MANUAL",
    "footnote": "It takes around 7 days for rewards to be delivered",
    "line_items": [{
      "id": "8d14t84kcvupxqj",
      "label": "$10 Amazon Gift Card",
      "requested": true
    }],
    "custom_fields": [{
      "id": "zzvqi0ygechgacj",
      "name": "Email",
      "desc": "Your email to receive gift card",
      "type": "EMAIL",
      "value": "johnd66@gmail.com"
    }]
  },
  "status": "FOLLOWUP",
  "created_timestamp": 1560259060
}

Patch incentivized reviewer with given ID.

HTTP Request

PATCH https://api.onvoard.com/v1/incentivized-reviewers/:recipient_id

Returns

Modified incentivized reviewer object if patch succeeded.

Arguments

Field Type Required Description
status enum (Incentivized Reviewer Status) No Status for incentivized reviewer.

List all Incentivized Reviewers

Example Request

curl 'https://api.onvoard.com/v1/incentivized-reviewers' \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "num_records": 1,
  "num_pages": 1,
  "current_page": 1,
  "results": [{
    "recipient": {
      "id": "rrrpt_gnnixeln0g5j4qaexgru4vnlo",
      "tracking_id": "6jYSgafXNU78AFaPzhSt",
      "test": false,
      "name": "",
      "email": "johndoe@gmail.com",
      "lag_window": null,
      "status": "DELIVERED",
      "sent_from": "CONSOLE",
      "error_msg": "",
      "created_timestamp": 1560258949,
      "reminder": {
        "status": "NA",
        "error_msg": ""
      },
      "activities": [{
          "id": "ldact_tjmz6hsha8qrpfyeogi5neupshfkr4",
          "type": "SENT_REVIEW_REQUEST",
          "created_timestamp": 1560258949
        },
        {
          "id": "ldact_hk8d1et2o5upw2rgqexej2jerpip0s",
          "type": "DELIVERED_REVIEW_REQUEST",
          "created_timestamp": 1560258949
        },
        {
          "id": "ldact_j9we8sristm96dgkkfi0y01yqdr5zm",
          "type": "CLICKED_REVIEW_REQUEST",
          "created_timestamp": 1560258957
        },
        {
          "id": "ldact_k1sxut7xm7tx7k1jxomwhrjb4cg09z",
          "type": "REQUESTED_REVIEW_REWARDS",
          "created_timestamp": 1560259060
        }
      ],
      "requester": {
        "id": "rwreq_awxloccld94xkfh",
        "name": "OnVoard G2"
      }
    },
    "reward": {
      "id": "rwd_4xg0gauv5x6n2ag",
      "desc": "All specified requirements must be fulfilled",
      "fulfillment_mode": "MANUAL",
      "footnote": "It takes around 7 days for rewards to be delivered",
      "line_items": [{
        "id": "8d14t84kcvupxqj",
        "label": "$10 Amazon Gift Card",
        "requested": true
      }],
      "custom_fields": [{
        "id": "zzvqi0ygechgacj",
        "name": "Email",
        "desc": "Your email to receive gift card",
        "type": "EMAIL",
        "value": "johnd66@gmail.com"
      }]
    },
    "status": "PENDING",
    "created_timestamp": 1560259060
  }]
}

List all incentivized reviewers user has access to.

HTTP Request

GET https://api.onvoard.com/v1/review-requests

Returns

List of incentivized reviewer objects.

Arguments

Field Type Description
keyword string Filter by specific keyword.
status enum (Incentivized Reviewer Status) Filter by incentivized reviewer status.
requester string Review Requester ID to filter.
account string Account ID to filter. Used when organization manage more than one account.
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.

Interviews

Represents a interview object. Interviews can be used to generate customer stories.

Interview Object

{
  "id": "itw_k8udjxohcn6ho3n",
  "passcode": "xz313fnwyu",
  "title": "Acme Corp",
  "content": "<p><em>Answer the questions below to complete your interview.</em></p>",
  "stage": "PENDING",
  "interviewee_name": "John Doe",
  "interviewee_company": "Acme Corp",
  "interviewee_email": "johndoe@gmail.com",
  "reward": null,
  "url": "https://onvoard.io/interviews/itw_k8udjxohcn6ho3n",
  "url_with_passcode": "https://onvoard.io/interviews/itw_k8udjxohcn6ho3n?passcode=xz313fnwyu",
  "created_from": "REQUESTER",
  "created_timestamp": 1560158662
}

Attributes

Field Type Description
id string Unique identifier for the object.
passcode string Passcode to access interview publicly.
title string Title of interview.
content string Interview content in HTML.
stage enum (Interview Stage) Interview stage. The default value is PENDING.
interviewee_name string Name of interviewee.
interviewee_company string Company of interviewee.
interviewee_email string Email of interviewee.
reward enum (Reward Object) Reward attached to this interview.
url string URL to access interview. User will be prompted to enter passcode.
url_with_passcode string URL to access interview. User will not be prompted to enter passcode.
created_from enum (Interview Created From) Origin where interview is created from.
created_timestamp integer Timestamp when interview is created.

Enums

List of available enum types under this resource.

Interview Created From

Value Description
API Interview created from API
CONSOLE Interview created from console
REQUESTER Interview created from requester

Interview Stage

Value Description
VOID Void
PENDING Pending. This is the default status.
RESPONDED Responded. PENDING interview automatically move to this stage after interviewee has responded.
FOLLOWUP Follow-up
COMPLETED Completed

Retrieve Interview

Example Request

curl 'https://api.onvoard.com/v1/interviews/rvw_7vomjp0vjokbq09' \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "id": "itw_k8udjxohcn6ho3n",
  "passcode": "xz313fnwyu",
  "title": "Acme Corp",
  "content": "<p><em>Answer the questions below to complete your interview.</em></p>",
  "stage": "PENDING",
  "interviewee_name": "John Doe",
  "interviewee_company": "Acme Corp",
  "interviewee_email": "johndoe@gmail.com",
  "reward": null,
  "url": "https://onvoard.io/interviews/itw_k8udjxohcn6ho3n",
  "url_with_passcode": "https://onvoard.io/interviews/itw_k8udjxohcn6ho3n?passcode=xz313fnwyu",
  "created_from": "REQUESTER",
  "created_timestamp": 1560158662
}

Retrieve interview with given ID.

HTTP Request

GET https://api.onvoard.com/v1/interviews/:interview_id

Returns

Interview object if valid ID was provided.

Patch Interview

Example Request

curl 'https://api.onvoard.com/v1/interviews/rvw_7vomjp0vjokbq09' \
-H 'X-API-Key: {API_KEY}'
-d stage="FOLLOWUP"

Example Response

{
  "id": "itw_k8udjxohcn6ho3n",
  "passcode": "xz313fnwyu",
  "title": "Acme Corp",
  "content": "<p><em>Answer the questions below to complete your interview.</em></p>",
  "stage": "FOLLOWUP",
  "interviewee_name": "John Doe",
  "interviewee_company": "Acme Corp",
  "interviewee_email": "johndoe@gmail.com",
  "reward": null,
  "url": "https://onvoard.io/interviews/itw_k8udjxohcn6ho3n",
  "url_with_passcode": "https://onvoard.io/interviews/itw_k8udjxohcn6ho3n?passcode=xz313fnwyu",
  "created_from": "REQUESTER",
  "created_timestamp": 1560158662
}

Patch interview with given ID.

HTTP Request

PATCH https://api.onvoard.com/v1/interviews/:interview_id

Returns

Modified interview object if patch succeeded.

Arguments

Field Type Required Description
stage enum (Interview Stage) No Stage of interview.

List all Interviews

Example Request

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

Example Response

{
  "num_records": 1,
  "num_pages": 1,
  "current_page": 1,
  "results": [{
    "id": "itw_k8udjxohcn6ho3n",
    "passcode": "xz313fnwyu",
    "title": "Acme Corp",
    "content": "<p><em>Answer the questions below to complete your interview.</em></p>",
    "stage": "PENDING",
    "interviewee_name": "John Doe",
    "interviewee_company": "Acme Corp",
    "interviewee_email": "johndoe@gmail.com",
    "reward": null,
    "url": "https://onvoard.io/interviews/itw_k8udjxohcn6ho3n",
    "url_with_passcode": "https://onvoard.io/interviews/itw_k8udjxohcn6ho3n?passcode=xz313fnwyu",
    "created_from": "REQUESTER",
    "created_timestamp": 1560158662
  }]
}

List all interviews user has access to.

HTTP Request

GET https://api.onvoard.com/v1/interviews

Returns

List of interview objects.

Arguments

Field Type Description
keyword string Filter by specific keyword.
created_from enum (Interview Created From) Filter by created from.
stage enum (Interview Stage) Filter by interview stage.
requester string Interview requester ID to filter.
account string Account ID to filter. Used when organization manage more than one account.
created_before integer Filter interviews created before provided timestamp.
created_after integer Filter interviews 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.

Interview Requesters

Represents a interview requester object. Can be used to send interview request via email.

Interview Requester Object

{
  "id": "iwreq_nhya6muq0q8pvxn",
  "name": "OnVoard Interview Requester",
  "content": "<p><em>Answer the questions below to complete your interview.</em></p>",
  "active": true,
  "tracking_on": true,
  "dedup_window": null
}

Attributes

Field Type Description
id string Unique identifier for the object.
name string Name for interview requester.
content string Interview content in HTML.
active boolean Active state of interview requester. Archived interview requester will be false.
tracking_on boolean Will be true if tracking is turned on.
dedup_window integer Number of days to lookback and deduplicate so you can avoid sending interview requests to the same email.

Retrieve Interview Requester

Example Request

curl 'https://api.onvoard.com/v1/interview-requesters/iwreq_nhya6muq0q8pvxn' \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "id": "iwreq_nhya6muq0q8pvxn",
  "name": "OnVoard Interview Requester",
  "content": "<p><em>Answer the questions below to complete your interview.</em></p>",
  "active": true,
  "tracking_on": true,
  "dedup_window": null
}

Retrieve interview requester with given ID.

HTTP Request

GET https://api.onvoard.com/v1/interview-requesters/:interview_requester_id

Returns

Interview requester object if valid ID was provided.

Patch Interview Requester

Example Request

curl 'https://api.onvoard.com/v1/interview-requesters/iwreq_nhya6muq0q8pvxn' \
-H 'X-API-Key: {API_KEY}'
-d active=false

Example Response

{
  "id": "iwreq_nhya6muq0q8pvxn",
  "name": "OnVoard Interview Requester",
  "content": "<p><em>Answer the questions below to complete your interview.</em></p>",
  "active": false,
  "tracking_on": true,
  "dedup_window": null
}

Patch interview requester with given ID.

HTTP Request

PATCH https://api.onvoard.com/v1/interview-requesters/:interview_requester_id

Returns

Modified interview requester object if patch succeeded.

Arguments

Field Type Required Description
active boolean No Active state of interview requester.

Send Interview Request

Example Request

curl 'https://api.onvoard.com/v1/interview-requesters/iwreq_nhya6muq0q8pvxn/send' \
-H 'X-API-Key: {API_KEY}'
-d name="John Doe" \
-d company="Acme Corp" \
-d email="johndoe@gmail.com"

Example Response

{
  "id": "iwrpt_trrr1grp5fcroahqe2nb583pn",
  "tracking_id": "TJSYiF3mzf8DeGCHEOhk",
  "test": false,
  "name": "John Doe",
  "email": "johndoe@gmail.com",
  "lag_window": null,
  "status": "NA",
  "sent_from": "CONSOLE",
  "error_msg": "",
  "created_timestamp": 1560237961,
  "reminder": {
    "status": "NA",
    "error_msg": ""
  },
  "activities": [{
    "id": "ldact_1v48gdzek5tshgbxflaoly97tx46kz",
    "type": "SENT_INTERVIEW_REQUEST",
    "created_timestamp": 1560237961
  }],
  "company": "Acme Corp",
  "requester": {
    "id": "iwreq_nhya6muq0q8pvxn",
    "name": "OnVoard Interview Requester"
  },
  "interview_instructions": {
    "status": "NA",
    "error_msg": ""
  }
}

Send interview request with given ID.

HTTP Request

POST https://api.onvoard.com/v1/interview-requesters/:interview_requester_id/send

Returns

Interview Requester Recipient Object if interview request was sent.

Arguments

Field Type Required Description
email string Yes Email address to send.
company string No Company name if recipient represents a company.
name string No Name of recipient. We will automatically extract first and last name.
lag_window integer No Send interview request after indicated number of minutes. If specified, lag window must be between 10 and 10080 (7 days).

List all Interview Requesters

Example Request

curl 'https://api.onvoard.com/v1/interview-requesters' \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "num_records": 1,
  "num_pages": 1,
  "current_page": 1,
  "results": [{
    "id": "iwreq_nhya6muq0q8pvxn",
    "name": "OnVoard Interview Requester",
    "content": "<p><em>Answer the questions below to complete your interview.</em></p>",
    "active": true,
    "tracking_on": true,
    "dedup_window": null
  }]
}

List all interview requesters user has access to.

HTTP Request

GET https://api.onvoard.com/v1/interview-requests

Returns

List of interview request objects.

Arguments

Field Type Description
active boolean Use true if you only want to return active interview requesters and false to return archived interview requests.
tracking_on boolean Filter by tracking status.
keyword string Filter by specific keyword.
account string Account ID to filter. Used when organization manage more than one account.
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.

Surveys

Represents a survey object.

Survey Object

{
  "id": "sur_m59c7sa4p0ogtfo",
  "on": true,
  "active": true,
  "tracking_on": true,
  "name": "NPS Survey",
  "distribution": "ONE_CLICK_EMAIL",
  "url": ""
}

Attributes

Field Type Description
id string Unique identifier for the object.
on boolean Survey status. If false, survey will not be eligible for distribution.
active boolean Active state of survey. Archived survey will be false.
tracking_on boolean Will be true if tracking is turned on.
name string Name for survey.
distribution enum (Survey Distribution) Distribution type for survey.
url string URL to view survey. This will only be set if distribution is LINK.

Enums

List of available enum types under this resource.

Survey Distribution

Value Description
WEB Web Distribution
ONE_CLICK_EMAIL One-Click Email Distribution
EMAIL Email Distribution
LINK Link Distribution

Retrieve Survey

Example Request

curl 'https://api.onvoard.com/v1/surveys/sur_m59c7sa4p0ogtfo' \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "id": "sur_m59c7sa4p0ogtfo",
  "on": true,
  "active": true,
  "tracking_on": true,
  "name": "NPS Survey",
  "distribution": "ONE_CLICK_EMAIL",
  "url": ""
}

Retrieve survey with given ID.

HTTP Request

GET https://api.onvoard.com/v1/surveys/:survey_id

Returns

Survey object if valid ID was provided.

Patch Survey

Example Request

curl 'https://api.onvoard.com/v1/surveys/sur_m59c7sa4p0ogtfo' \
-H 'X-API-Key: {API_KEY}'
-d active=false

Example Response

{
  "id": "sur_m59c7sa4p0ogtfo",
  "on": true,
  "active": false,
  "tracking_on": true,
  "name": "NPS Survey",
  "distribution": "ONE_CLICK_EMAIL",
  "url": ""
}

Patch survey with given ID.

HTTP Request

PATCH https://api.onvoard.com/v1/surveys/:survey_id

Returns

Modified survey object if patch succeeded.

Arguments

Field Type Required Description
on boolean No Status of survey
active boolean No Active state of survey.

Send Survey

Example Request

curl 'https://api.onvoard.com/v1/surveys/sur_m59c7sa4p0ogtfo/send' \
-H 'X-API-Key: {API_KEY}'
-d name="John Doe" \
-d email="johndoe@gmail.com"

Example Response

{
  "id": "srrpt_3uml0c7nwjytalusxc6jsvqvm",
  "tracking_id": "sUhnwbdRkwpv16V3bbG3",
  "test": false,
  "name": "John Doe",
  "email": "johndoe@gmail.com",
  "lag_window": null,
  "status": "NA",
  "sent_from": "CONSOLE",
  "error_msg": "",
  "created_timestamp": 1560238191,
  "reminder": {
    "status": "NA",
    "error_msg": ""
  },
  "activities": [{
    "id": "ldact_1v48gdzek5tshgbxflaoly97tx46kz",
    "type": "SENT_SURVEY",
    "created_timestamp": 1560237961
  }],
  "survey": {
    "id": "sur_m59c7sa4p0ogtfo",
    "name": "NPS Survey"
  }
}

Send survey with given ID.
Only email based surveys are eligible for sending. Survey's distribution must be EMAIL or ONE_CLICK_EMAIL.

HTTP Request

POST https://api.onvoard.com/v1/surveys/:survey_id/send

Returns

Survey Recipient Object if survey was sent.

Arguments

Field Type Required Description
email string Yes Email address to send.
name string No Name of recipient. We will automatically extract first and last name.
lag_window integer No Send survey after indicated number of minutes. If specified, lag window must be between 10 and 10080 (7 days).

List all Surveys

Example Request

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

Example Response

{
  "num_records": 1,
  "num_pages": 1,
  "current_page": 1,
  "results": [{
    "id": "sur_m59c7sa4p0ogtfo",
    "on": true,
    "active": true,
    "tracking_on": true,
    "name": "NPS Survey",
    "distribution": "ONE_CLICK_EMAIL",
    "url": ""
  }]
}

List all surveys user has access to.

HTTP Request

GET https://api.onvoard.com/v1/surveys

Returns

List of survey objects.

Arguments

Field Type Description
active boolean Use true if you only want to return active surveys and false to return archived surveys.
tracking_on boolean Filter by tracking status.
keyword string Filter by specific keyword.
distribution enum (Survey Distribution) Survey distribution to filter.
account string Account ID to filter. Used when organization manage more than one account.
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.

Survey Respondents

Represents a survey respondent object. Created when someone responds to a survey.

Survey Respondent Object

{
  "id": "sres_m94pn93kldx6ftf",
  "survey": {
    "id": "sur_m59c7sa4p0ogtfo",
    "name": "NPS Survey"
  },
  "traits": [{
    "id": "trt_fvquqiaux53rdcb",
    "key": "email",
    "key_display": "Email",
    "value": "johndoe@gmail.com",
    "value_type": "email"
  }],
  "answers": [{
    "id": "srasw_4ws3uioc3tokrhs",
    "question": {
      "id": "srqn_5zn4ytxqf6wxqg1",
      "type": "RATING",
      "title": "How likely would you recommend us to your friend?"
    },
    "text_value": "",
    "email_value": "",
    "url_value": "",
    "rating_value": 9,
    "selection_values": [],
    "value_in_text": "9",
    "created_timestamp": 1560158706
  }],
  "answered_all_questions": true,
  "created_timestamp": 1560158706
}

Attributes

Field Type Description
id string Unique identifier for the object.
survey.id string Unique identifier for survey.
survey.name string Name for survey.
traits[] object (Trait Object) Traits for respondent.
answers[] object (Survey Answer Object) Answers for survey response.
answered_all_questions boolean Will be true if every questions has been answered.
created_timestamp integer Timestamp when survey response is created.

Survey Answer Object

Represents a survey answer object.

{
  "id": "srasw_4ws3uioc3tokrhs",
  "question": {
    "id": "srqn_5zn4ytxqf6wxqg1",
    "type": "RATING",
    "title": "How likely would you recommend us to your friend?"
  },
  "text_value": "",
  "email_value": "",
  "url_value": "",
  "rating_value": 9,
  "selection_values": [],
  "value_in_text": "9",
  "created_timestamp": 1560158706
}

Attributes

Field Type Description
id string Unique identifier for answer.
question.id string Unique identifier for question.
question.type enum (Survey Question Type) Type for question.
question.title string Question title.
text_value string Text value for answer. Will be specified if question type is SINGLE_LINE_TEXT or MULTI_LINE_TEXT.
email_value string Email value for answer. Will be specified if question type is EMAIL.
url_value string URL value for answer. Will be specified if question type is URL.
rating_value integer Rating value for answer. Value can range from 1 to 10. Will be specified if question type is RATING.
selection_values[].id string Unique identifier for selection value.
selection_values[].option object (Survey Question Option Object) Selected option for answer.
selection_values[].comment string Added comment for selected option.
value_in_text string Normalized value in text string. This is especially useful if you want to display selection_values in text.
created_timestamp integer Timestamp when answer is added.

Survey Question Option Object

Represents a survey question option object.

{
  "id": "dirhg0yyqz2cevi",
  "label": "Search Engine",
  "enable_comment": false,
  "disabled": false,
  "comment_placeholder": ""
}

Attributes

Field Type Description
id string Unique identifier for question option.
label string Label for question option.
enable_comment boolean If true, respondent can add comment for option.
disabled boolean If true, option will be disabled for selection.
comment_placeholder string Placeholder text for comment.

Enums

List of available enum types under this resource.

Survey Question Type

Value Description
SINGLE_SELECTION Question with single selected answer. Similar to radio buttons.
MULTIPLE_SELECTIONS Question with multiple selected answers. Similar to checkbox.
SINGLE_LINE_TEXT Question with 1 line answer. Similar to input.
MULTI_LINE_TEXT Question with multi-line answer. Similar to textarea.
EMAIL Question that requires email as answer.
URL Question that requires url as answer.
RATING Question for 1-10 rating scale answer.

Retrieve Survey Respondent

Example Request

curl 'https://api.onvoard.com/v1/survey-respondents/sres_m94pn93kldx6ftf' \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "id": "sres_m94pn93kldx6ftf",
  "survey": {
    "id": "sur_m59c7sa4p0ogtfo",
    "name": "NPS Survey",
  },
  "traits": [{
    "id": "trt_fvquqiaux53rdcb",
    "key": "email",
    "key_display": "Email",
    "value": "johndoe@gmail.com",
    "value_type": "email"
  }],
  "answers": [{
    "id": "srasw_4ws3uioc3tokrhs",
    "question": {
      "id": "srqn_5zn4ytxqf6wxqg1",
      "type": "RATING",
      "title": "How likely would you recommend us to your friend?"
    },
    "text_value": "",
    "email_value": "",
    "url_value": "",
    "rating_value": 9,
    "selection_values": [],
    "value_in_text": "9",
    "created_timestamp": 1560158706
  }],
  "answered_all_questions": true,
  "created_timestamp": 1560158706
}

Retrieve survey respondent with given ID.

HTTP Request

GET https://api.onvoard.com/v1/survey-respondents/:survey_respondent_id

Returns

Interview object if valid ID was provided.

List all Survey Respondents

Example Request

curl 'https://api.onvoard.com/v1/survey-respondents' \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "num_records": 1,
  "num_pages": 1,
  "current_page": 1,
  "results": [{
    "id": "sres_m94pn93kldx6ftf",
    "survey": {
      "id": "sur_m59c7sa4p0ogtfo",
      "name": "NPS Survey",
    },
    "traits": [{
      "id": "trt_fvquqiaux53rdcb",
      "key": "email",
      "key_display": "Email",
      "value": "johndoe@gmail.com",
      "value_type": "email"
    }],
    "answers": [{
      "id": "srasw_4ws3uioc3tokrhs",
      "question": {
        "id": "srqn_5zn4ytxqf6wxqg1",
        "type": "RATING",
        "title": "How likely would you recommend us to your friend?"
      },
      "text_value": "",
      "email_value": "",
      "url_value": "",
      "rating_value": 9,
      "selection_values": [],
      "value_in_text": "9",
      "created_timestamp": 1560158706
    }],
    "answered_all_questions": true,
    "created_timestamp": 1560158706
  }]
}

List all survey respondents user has access to.

HTTP Request

GET https://api.onvoard.com/v1/survey-respondents

Returns

List of survey respondent objects.

Arguments

Field Type Description
keyword string Filter by specific keyword.
survey string Survey ID to filter.
account string Account ID to filter. Used when organization manage more than one account.
created_before integer Filter survey respondents created before provided timestamp.
created_after integer Filter survey respondents 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.

Stories

Represents a story object.

Story Object

{
  "id": "stry_clg68ervlsw1ew9",
  "site": {
    "id": "ssite_bujb94f4wz3kago",
    "name": "customers.onvoard.com",
    "layout": "ORGANIZATION"
  },
  "slug": "acme-corp",
  "headline": "How Acme Corp get 65% more customers with OnVoard",
  "content": "<p>It presents many opportunities for car manufacturers to sell more than ever before.<br/></p>",
  "published": true,
  "num_views": 0,
  "sort_order": 1,
  "person_name": "",
  "person_credential": "",
  "person_quote": "",
  "organization_name": "Acme Corp",
  "rep_on": true,
  "rep_name": "John Doe",
  "rep_position": "Marketing Director",
  "rep_quote": "We needed a place on our website where we could motivate visitors to give us their permission",
  "logo_pic_media": null,
  "hero_pic_media": null,
  "person_pic_media": null,
  "rep_pic_media": null,
  "attributes": [{
      "id": "statr_9l23muh9nomixuy",
      "type": "URL",
      "text_name": "",
      "text_value": "",
      "url_name": "Website",
      "url_value": "https://example.com",
      "category_value": null
    },
    {
      "id": "statr_h4lb9jyhbnrde8c",
      "type": "CATEGORY",
      "text_name": "",
      "text_value": "",
      "url_name": "",
      "url_value": "",
      "category_value": {
        "id": "stcv_cyznhccsaqri10g",
        "category": {
          "id": "stcat_8ku4c8p6su0lpff",
          "name": "Region",
          "slug": "region"
        },
        "name": "Asia Pacific",
        "slug": "asia_pacific"
      }
    }
  ],
  "default_article_url": "https://onvoard.io/stories/onvoard/acme-corp",
  "custom_article_url": "",
  "pdf_url": "https://storage.googleapis.com/onvoard/upload/story/pdf-media/stry_clg68ervlsw1ew9.pdf"
}

Attributes

Field Type Description
id string Unique identifier for the object.
site.id string Unique identifier for site.
site.name string Name for site.
site.layout enum (Story Layout) Layout to display story.
slug string Slug for story.
headline string Headline of story.
content string Story content in HTML.
published boolean If false, story will not be available for viewing publicly.
num_views integer Number of unique views for story.
sort_order integer Sort order for story in ascending order. 1 should be shown before 2.
person_name string Name of person story is written for. Used for PERSON layout.
person_credential string Credential of person story is written for. Used for PERSON layout.
person_quote string Quote from person story is written for. Used for PERSON layout.
organization_name string Name of organization story is written for. Used for ORGANIZATION layout.
rep_on boolean If true, we will use representative details for ORGANIZATION layout.
rep_name string Name of organization's representative. Used for ORGANIZATION layout.
rep_position string Position of organization's representative. Used for ORGANIZATION layout.
rep_quote string Quote from organization's representative. Used for ORGANIZATION layout.
logo_pic_media object (Image Media Object) Organization's logo. Used for ORGANIZATION layout.
hero_pic_media object (Image Media Object) Hero image for story.
person_pic_media object (Image Media Object) Profile picture of person story is written for. Used for PERSON layout.
rep_pic_media object (Image Media Object) Profile picture of organization's representative. Used for ORGANIZATION layout.
attributes[] object (Story Attribute Object) Attributes tagged to story.
default_article_url string Default url to access story in OnVoard's domain.
custom_article_url string Custom url to access story in specified custom domain.
pdf_url string Url to access PDF generated from story.

Story Attribute Object

Represents a story attribute object.

{
  "id": "statr_h4lb9jyhbnrde8c",
  "type": "CATEGORY",
  "text_name": "",
  "text_value": "",
  "url_name": "",
  "url_value": "",
  "category_value": {
    "id": "stcv_cyznhccsaqri10g",
    "category": {
      "id": "stcat_8ku4c8p6su0lpff",
      "name": "Region",
      "slug": "region"
    },
    "name": "Asia Pacific",
    "slug": "asia_pacific"
  }
}

Attributes

Field Type Description
id string Unique identifier for object.
type enum (Story Attribute Type) Type for attribute.
text_name string Name for text attribute. Will be specified if type is TEXT.
text_value string Value for text attribute. Will be specified if type is TEXT.
url_name string Name for url attribute. Will be specified if type is URL.
url_value string Value for url attribute. Will be specified if type is URL.
category_value object (Story Category Value Object) Linked category value category. Will be specified if type is CATEGORY.

Story Category Value Object

Represents a story category value object.

{
  "id": "stcv_cyznhccsaqri10g",
  "category": {
    "id": "stcat_8ku4c8p6su0lpff",
    "name": "Region",
    "slug": "region"
  },
  "name": "Asia Pacific",
  "slug": "asia_pacific"
}

Attributes

Field Type Description
id string Unique identifier for object.
category object (Story Category Object) Linked category for this value object.
name string Name for category value.
slug string Slug for category value.

Story Category Object

Represents a story category object.

{
  "id": "stcat_8ku4c8p6su0lpff",
  "name": "Region",
  "slug": "region"
}

Attributes

Field Type Description
id string Unique identifier for object.
name string Name for category.
slug string Slug for category.

Enums

List of available enum types under this resource.

Story Attribute Type

Value Description
TEXT Attribute value in text
URL Attribute value in url
CATEGORY Attribute value in predefined category

Story Layout

Value Description
ORGANIZATION Layout for organization stories
PERSON Layout for person stories

Retrieve Story

Example Request

curl 'https://api.onvoard.com/v1/stories/stry_clg68ervlsw1ew9' \
-H 'X-API-Key: {API_KEY}'

Example Response

{
  "id": "stry_clg68ervlsw1ew9",
  "site": {
    "id": "ssite_bujb94f4wz3kago",
    "name": "customers.onvoard.com",
    "layout": "ORGANIZATION"
  },
  "slug": "acme-corp",
  "headline": "How Acme Corp get 65% more customers with OnVoard",
  "content": "<p>It presents many opportunities for car manufacturers to sell more than ever before.<br/></p>",
  "published": true,
  "num_views": 0,
  "sort_order": 1,
  "person_name": "",
  "person_credential": "",
  "person_quote": "",
  "organization_name": "Acme Corp",
  "rep_on": true,
  "rep_name": "John Doe",
  "rep_position": "Marketing Director",
  "rep_quote": "We needed a place on our website where we could motivate visitors to give us their permission",
  "logo_pic_media": null,
  "hero_pic_media": null,
  "person_pic_media": null,
  "rep_pic_media": null,
  "attributes": [{
      "id": "statr_9l23muh9nomixuy",
      "type": "URL",
      "text_name": "",
      "text_value": "",
      "url_name": "Website",
      "url_value": "https://example.com",
      "category_value": null
    },
    {
      "id": "statr_h4lb9jyhbnrde8c",
      "type": "CATEGORY",
      "text_name": "",
      "text_value": "",
      "url_name": "",
      "url_value": "",
      "category_value": {
        "id": "stcv_cyznhccsaqri10g",
        "category": {
          "id": "stcat_8ku4c8p6su0lpff",
          "name": "Region",
          "slug": "region"
        },
        "name": "Asia Pacific",
        "slug": "asia_pacific"
      }
    }
  ],
  "default_article_url": "https://onvoard.io/stories/onvoard/acme-corp",
  "custom_article_url": "",
  "pdf_url": "https://storage.googleapis.com/onvoard/upload/story/pdf-media/stry_clg68ervlsw1ew9.pdf"
}

Retrieve story with given ID.

HTTP Request

GET https://api.onvoard.com/v1/stories/:story_id

Returns

Story object if valid ID was provided.

Patch Story

Example Request

curl 'https://api.onvoard.com/v1/stories/stry_clg68ervlsw1ew9' \
-H 'X-API-Key: {API_KEY}'
-d published=false

Example Response

{
  "id": "stry_clg68ervlsw1ew9",
  "site": {
    "id": "ssite_bujb94f4wz3kago",
    "name": "customers.onvoard.com",
    "layout": "ORGANIZATION"
  },
  "slug": "acme-corp",
  "headline": "How Acme Corp get 65% more customers with OnVoard",
  "content": "<p>It presents many opportunities for car manufacturers to sell more than ever before.<br/></p>",
  "published": false,
  "num_views": 0,
  "sort_order": 1,
  "person_name": "",
  "person_credential": "",
  "person_quote": "",
  "organization_name": "Acme Corp",
  "rep_on": true,
  "rep_name": "John Doe",
  "rep_position": "Marketing Director",
  "rep_quote": "We needed a place on our website where we could motivate visitors to give us their permission",
  "logo_pic_media": null,
  "hero_pic_media": null,
  "person_pic_media": null,
  "rep_pic_media": null,
  "attributes": [{
      "id": "statr_9l23muh9nomixuy",
      "type": "URL",
      "text_name": "",
      "text_value": "",
      "url_name": "Website",
      "url_value": "https://example.com",
      "category_value": null
    },
    {
      "id": "statr_h4lb9jyhbnrde8c",
      "type": "CATEGORY",
      "text_name": "",
      "text_value": "",
      "url_name": "",
      "url_value": "",
      "category_value": {
        "id": "stcv_cyznhccsaqri10g",
        "category": {
          "id": "stcat_8ku4c8p6su0lpff",
          "name": "Region",
          "slug": "region"
        },
        "name": "Asia Pacific",
        "slug": "asia_pacific"
      }
    }
  ],
  "default_article_url": "https://onvoard.io/stories/onvoard/acme-corp",
  "custom_article_url": "",
  "pdf_url": "https://storage.googleapis.com/onvoard/upload/story/pdf-media/stry_clg68ervlsw1ew9.pdf"
}

Patch story with given ID.

HTTP Request

PATCH https://api.onvoard.com/v1/stories/:story_id

Returns

Modified story object if patch succeeded.

Arguments

Field Type Required Description
slug string No Slug of story. Must have at least 3 characters
published boolean No Published state for story.

List all Stories

Example Request

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

Example Response

{
  "num_records": 1,
  "num_pages": 1,
  "current_page": 1,
  "results": [{
    "id": "stry_clg68ervlsw1ew9",
    "site": {
      "id": "ssite_bujb94f4wz3kago",
      "name": "customers.onvoard.com",
      "layout": "ORGANIZATION"
    },
    "slug": "acme-corp",
    "headline": "How Acme Corp get 65% more customers with OnVoard",
    "content": "<p>It presents many opportunities for car manufacturers to sell more than ever before.<br/></p>",
    "published": true,
    "num_views": 0,
    "sort_order": 1,
    "person_name": "",
    "person_credential": "",
    "person_quote": "",
    "organization_name": "Acme Corp",
    "rep_on": true,
    "rep_name": "John Doe",
    "rep_position": "Marketing Director",
    "rep_quote": "We needed a place on our website where we could motivate visitors to give us their permission",
    "logo_pic_media": null,
    "hero_pic_media": null,
    "person_pic_media": null,
    "rep_pic_media": null,
    "attributes": [{
        "id": "statr_9l23muh9nomixuy",
        "type": "URL",
        "text_name": "",
        "text_value": "",
        "url_name": "Website",
        "url_value": "https://example.com",
        "category_value": null
      },
      {
        "id": "statr_h4lb9jyhbnrde8c",
        "type": "CATEGORY",
        "text_name": "",
        "text_value": "",
        "url_name": "",
        "url_value": "",
        "category_value": {
          "id": "stcv_cyznhccsaqri10g",
          "category": {
            "id": "stcat_8ku4c8p6su0lpff",
            "name": "Region",
            "slug": "region"
          },
          "name": "Asia Pacific",
          "slug": "asia_pacific"
        }
      }
    ],
    "default_article_url": "https://onvoard.io/stories/onvoard/acme-corp",
    "custom_article_url": "",
    "pdf_url": "https://storage.googleapis.com/onvoard/upload/story/pdf-media/stry_clg68ervlsw1ew9.pdf"
  }]
}

List all stories user has access to.

HTTP Request

GET https://api.onvoard.com/v1/stories

Returns

List of story objects.

Arguments

Field Type Description
keyword string Filter by specific keyword.
published boolean Use true if you only want to return published stories and false to return unpublished stories.
site string Story site ID to filter.
account string Account ID to filter. Used when organization manage more than one account.
created_before integer Filter stories created before provided timestamp.
created_after integer Filter stories 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.

Recipients

Recipients are users who have recieved email from OnVoard's service.

Recipient Object

Abstract recipient object. This serve as the base object for other recipient extensions.

{
  "id": "rrrpt_3e6mz1ur0aoycy8v7jsj8aekw",
  "tracking_id": "r6kMe3QwGjE0pilgCk7Q",
  "test": false,
  "name": "John Doe",
  "email": "johndoe@gmail.com",
  "lag_window": null,
  "status": "NA",
  "sent_from": "CONSOLE",
  "error_msg": "",
  "created_timestamp": 1560229938,
  "reminder": {
    "status": "NA",
    "error_msg": ""
  },
  "activities": [{
    "id": "ldact_1v48gdzek5tshgbxflaoly97tx46kz",
    "type": "SENT_REVIEW_REQUEST",
    "created_timestamp": 1560158564
  }]
}

Attributes

Field Type Description
id string Unique identifier for the object.
tracking_id string Tracking ID for recipient.
test boolean Will be true for test recipient.
name string Recipient's name.
email string Recipient's email.
lag_window integer Number of minutes delayed before email was sent to recipient.
status enum (Recipient Status) Status of recipient.
sent_from enum (Sent From) Origin where recipient was sent from.
error_msg string Details of error. Will be provided if status is FAILED.
created_timestamp integer Timestamp when recipient is created.
reminder.status enum (Recipient Status) Status for reminder. By default, this will be NA if reminder is not yet eligible for sending.
reminder.error_msg string Details of error. Will be provided if reminder.status is FAILED.
activities[].id string Unique identifier for activity.
activities[].type enum (Activity Type) Type of activity.
activities[].created_timestamp integer Timestamp when activity occurred.

Review Requester Recipient Object

Recipient for review request. Inherits all fields from Recipient Object with additional fields below.

{
  "id": "rrrpt_3e6mz1ur0aoycy8v7jsj8aekw",
  "tracking_id": "r6kMe3QwGjE0pilgCk7Q",
  "test": false,
  "name": "John Doe",
  "email": "johndoe@gmail.com",
  "lag_window": null,
  "status": "NA",
  "sent_from": "CONSOLE",
  "error_msg": "",
  "created_timestamp": 1560229938,
  "reminder": {
    "status": "NA",
    "error_msg": ""
  },
  "activities": [{
    "id": "ldact_1v48gdzek5tshgbxflaoly97tx46kz",
    "type": "SENT_REVIEW_REQUEST",
    "created_timestamp": 1560158564
  }],
  "requester": {
    "id": "rwreq_awxloccld94xkfh",
    "name": "OnVoard G2"
  }
}

Attributes

Field Type Description
requester.id string Unique identifier for review requester.
requester.name string Name for review requester.

Interview Requester Recipient Object

Recipient for interview request. Inherits all fields from Recipient Object with additional fields below.

{
  "id": "iwrpt_trrr1grp5fcroahqe2nb583pn",
  "tracking_id": "TJSYiF3mzf8DeGCHEOhk",
  "test": false,
  "name": "John Doe",
  "email": "johndoe@gmail.com",
  "lag_window": null,
  "status": "NA",
  "sent_from": "CONSOLE",
  "error_msg": "",
  "created_timestamp": 1560237961,
  "reminder": {
    "status": "NA",
    "error_msg": ""
  },
  "activities": [{
    "id": "ldact_1v48gdzek5tshgbxflaoly97tx46kz",
    "type": "SENT_INTERVIEW_REQUEST",
    "created_timestamp": 1560237961
  }],
  "company": "Acme Corp",
  "requester": {
    "id": "iwreq_nhya6muq0q8pvxn",
    "name": "OnVoard Interview Requester"
  },
  "interview_instructions": {
    "status": "NA",
    "error_msg": ""
  }
}

Attributes

Field Type Description
company string Recipient's company name.
requester.id string Unique identifier for interview requester.
requester.name string Name for interview requester.
interview_instructions.status enum (Recipient Status) Status for interview instructions. By default, this will be NA if instructions is not yet eligible for sending.
interview_instructions.error_msg string Details of error. Will be provided if interview_instructions.status is FAILED.

Survey Recipient Object

Recipient for survey. Inherits all fields from Recipient Object with additional fields below.

{
  "id": "srrpt_3uml0c7nwjytalusxc6jsvqvm",
  "tracking_id": "sUhnwbdRkwpv16V3bbG3",
  "test": false,
  "name": "John Doe",
  "email": "johndoe@gmail.com",
  "lag_window": null,
  "status": "NA",
  "sent_from": "CONSOLE",
  "error_msg": "",
  "created_timestamp": 1560238191,
  "reminder": {
    "status": "NA",
    "error_msg": ""
  },
  "activities": [{
    "id": "ldact_1v48gdzek5tshgbxflaoly97tx46kz",
    "type": "SENT_SURVEY",
    "created_timestamp": 1560237961
  }],
  "survey": {
    "id": "sur_m59c7sa4p0ogtfo",
    "name": "NPS Survey"
  }
}

Attributes

Field Type Description
survey.id string Unique identifier for survey.
survey.name string Name for survey.

Enums

List of available enum types under this resource.

Recipient Status

Value Description
NA Not applicable for sending
QUEUED Recipient is queued and waiting to be sent. Used when lag_window is specified.
FAILED Encountered failure when we tried to send to recipient
SENDING Currently sending to recipient
DELIVERED Successfully sent to recipient

Sent From

Value Description
API Recipient is sent from API calls
CONSOLE Recipient is sent from console
CONSOLE_BULK Recipient is sent from console via bulk upload
TRIGGERS Recipient is sent from triggers executed
SURVEY_ACTIONS Recipient is sent from survey actions
SURVEY_RESPONDENT_WORKFLOWS Recipient is sent from survey respondent workflows
RECURRING Recipient is sent from recurring tasks such as resurveys

Activity Type

Value Description
SENT_REVIEW_REQUEST Sent Review Request
DELIVERED_REVIEW_REQUEST Delivered Review Request
OPENED_REVIEW_REQUEST Opened Review Request
CLICKED_REVIEW_REQUEST Clicked Review Request
REQUESTED_REVIEW_REQUEST Requested Review Request
SENT_REVIEW_REMINDER Sent Review Reminder
DELIVERED_REVIEW_REMINDER Delivered Review Reminder
OPENED_REVIEW_REMINDER Opened Review Reminder
CLICKED_REVIEW_REMINDER Clicked Review Reminder

Value Description
SENT_INTERVIEW_REQUEST Sent Interview Request
DELIVERED_INTERVIEW_REQUEST Delivered Interview Request
OPENED_INTERVIEW_REQUEST Opened Interview Request
CLICKED_INTERVIEW_REQUEST Clicked Interview Request
SENT_INTERVIEW_REMINDER Sent Interview Reminder
DELIVERED_INTERVIEW_REMINDER Delivered Interview Reminder
OPENED_INTERVIEW_REMINDER Opened Interview Reminder
CLICKED_INTERVIEW_REMINDER Clicked Interview Reminder
SENT_INTERVIEW_INSTRUCTIONS Sent Interview Instructions
DELIVERED_INTERVIEW_INSTRUCTIONS Delivered Interview Instructions
OPENED_INTERVIEW_INSTRUCTIONS Opened Interview Instructions
CLICKED_INTERVIEW_INSTRUCTIONS Clicked Interview Instructions
RESPONDED_INTERVIEW Responded Interview
Value Description
SENT_SURVEY Sent Survey
DELIVERED_SURVEY Delivered Survey
OPENED_SURVEY Opened Survey
CLICKED_SURVEY Clicked Survey
SENT_SURVEY_REMINDER Sent Survey Reminder
DELIVERED_SURVEY_REMINDER Delivered Survey Reminder
OPENED_SURVEY_REMINDER Opened Survey Reminder
CLICKED_SURVEY_REMINDER Clicked Survey Reminder
RESPONDED_SURVEY Responded Survey

Data Types

Various data types used for API endpoints.

Image Media Object

Object for representing image media.

{
  "id": "file_o60kak2khvvg0lw",
  "file_url": "https://storage.googleapis.com/onvoard/upload/review-requester/logo-pic-media/12ad7a9c7b0e7743a879.png",
  "height": 300,
  "width": 250,
  "created_timestamp": 1543414453
}

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_timestamp integer Created timestamp of image.

Reward Object

A single reward object may be attached with "multiple rewards" by having more than one line item. Custom fields are used to collect additional information from user for rewards fulfillments.

{
  "id": "rwd_0hhtxmc0lsq710r",
  "desc": "All specified requirements must be fulfilled",
  "fulfillment_mode": "MANUAL",
  "footnote": "It takes around 7 days for rewards to be delivered",
  "line_items": [{
    "id": "pec8v7b9hja21u6",
    "label": "$10 Amazon Gift Card",
    "requested": false
  }],
  "custom_fields": [{
    "id": "djqifrhipmp2h1a",
    "name": "Email",
    "desc": "Your email to receive gift card",
    "type": "EMAIL",
    "value": ""
  }]
}

Attributes

Field Type Description
id string Unique identifier for the object.
desc string Reward description.
fulfillment_mode enum (Fulfillment Mode) Mode which reward will be fulfilled.
footnote string Additional information for reward that will be added at the end.
line_items[].id string Unique identifier for the object.
line_items[].label string Label that states reward user can expect.
line_items[].requested boolean Will be true if line item is requested by user.
custom_fields[].id string Unique identifier for the object.
custom_fields[].name string Name for custom fields.
custom_fields[].desc string Description for custom fields.
custom_fields[].type enum (Reward Custom Field Type) Type for custom field value.
custom_fields[].value string Value for this custom field. Will be empty if not specified by user.

Trait Object

Trait refers to attributes that describes a person. Some commonly used traits includes name, email, company.

{
  "id": "trt_fvquqiaux53rdcb",
  "key": "email",
  "key_display": "Email",
  "value": "johndoe@gmail.com",
  "value_type": "email"
}

Attributes

Field Type Description
id string Unique identifier for object.
key string Key to identify trait. Characters must be lowercase alphanumeric characters and underscores.
key_display string Beautified display for key. For example first_name for key will be rendered as First Name.
value string Value for trait.
value_type enum (Trait Value Type) Value type for trait.

Enums

List of available enum types under this resource.

Fulfillment Mode

Value Description
MANUAL Fulfill rewards manually. Currently this is the only option.

Reward Custom Field Type

Value Description
SINGLE_LINE_TEXT Single-line text which will display as input
MULTI_LINE_TEXT Multi-line text which will display as textarea
EMAIL Email value
URL URL value

Trait Value Type

Value Description
string Value is used to represent text string
integer Value is used to represent integer number
float Value is used to represent float number
boolean Value is used to represent boolean
timestamp Value is used to represent timestamp
email Value is used to represent email
url Value is used to represent url