The Zap Reports API is organized around REST. Our API has predictable resource-oriented URLs and functions similarly to most modern day APIs.
Authentication is handled via an API Key and Secret and all data is returned in a standardized format.
At its current stage the Zap Reports API supports only GET, POST, and Patch requests.
All requests to the API start with the base url shown here.
In addition, all requests require a valid API pair to be sent in the headers of a request serving as your method of authentication.
PRODUCTION EXAMPLE
POST https://api.zapreports.com/v1/connect/contactsTo validate with the the Zap Reports API, requests will be checked for valid credentials sent in the headers of the request. Headers must contain an API set containing your API Key and API Secret.
All Secret keys are protected via a one way hash, if you lose your API secret you must roll it from your Zap Reports Dashboard.
If a request is made either leaving out this key pairing or with incorrect values a 403 FORBIDDEN status code will be returned
Requests to the Zap Reports API are limited to 120 per minute (roughly 2 per second). If the rate limit is reached a 429 status code will be returned.
NOTE that this limit exists across all endpoints and resources.
Contacts are the core resources needed to connect to zap reports. Everything runs through a request to either find or create a contact and then a POST request to to invite the contact to pull their needed documents.
Note that simply creating a contact will not give them permissions to pull their documents. If a contact has not yet had their documents requested the portal will deny them access. This is explained in more depth under the /v1/connect/contacts/:_id/request endpoint.
| Property | Type | Values |
|---|---|---|
| _id | ID | A unique identifier for the contact |
| company | ID | A unique ID of the company the contact belongs to. This will be your company ID |
| given_name | string | The contact's first name |
| family_name | string | The contact's last name |
| display_name | string | The contact's full name |
| string | The email of the contact. Must be a valid email address | |
| phone | string | The phone number of a contact formatted as +12223334444. Must be a valid phone number |
| report_status | string | null, requested, in progress, finished |
| access_code | string | An access code required by the contact to pull reports in their portal. |
| integrations | array | An array of objects representing custom fields for outbound integrations. |
| deleted | boolean | true or false |
| updated_at | number | A unix timestamp of when the contact was last updated. |
| created_at | number | A unix timestamp of when the contact was created. |
POST: /v1/connect/contactsReturns success true of false if contact was created.
NOTE that a contact may not share the same email or phone fields as another contact and must have either a family_name, email, or phone property for creation to be successfull.
In implementing this example make sure to change the phone field to a real phone number. Zap Reports will reject any email or phone fields that are not valid.
** If you wish to also send out a request for documents immediately after creating a contact, pass the property "request": true as an additional parameter
{
given_name: 'John',
family_name: 'Doe',
email: 'johndoe@gmail.com',
phone: '1112223333',
request: true,
// contact support or see webhooks
// below for integration details
integrations: []
}{
success: true,
message: [],
user_message: [],
api_version: '1.0',
path: 'POST: /v1/connect/contacts',
time: 1636392789,
milliseconds: 222,
data: {
given_name: 'john',
family_name: 'doe',
display_name: 'John Doe',
report_status: 'null',
email: 'johndoe@gmail.com',
phone: '+11112223333'
deleted: false,
_id: '61895f552e103829b422e9b5',
company: '61895f55ca365c29b8dea7a6',
updated_at: 1636392789,
created_at: 1636392789,
access_code: '346688',
integrations: []
}
}PATCH: /v1/connect/contacts/:_idReturns success true of false if contact was updated.
NOTE that a contact may not share the same email or phone fields as another contact.
In implementing this example make sure to change the phone field to a real phone number. Zap Reports will reject any email or phone fields that are not valid.
** If you pass a value to the "integrations" array you must pass along all values associated with the objects inside it. Do not pass just one property (or object if you have multiple integrations) as this will erase any previous integration values.
{
given_name: 'John',
family_name: 'Doe',
email: 'johndoe@gmail.com',
phone: '1112223333',
// contact support for custom
// integration details
integrations: []
}{
success: true,
message: [],
user_message: [],
api_version: '1.0',
path: 'PATCH: /v1/connect/contacts/61895f552e103829b422e9b5',
time: 1636392789,
milliseconds: 222,
data: {
given_name: 'john',
family_name: 'doe',
display_name: 'John Doe',
report_status: 'null',
email: 'johndoe@gmail.com',
phone: '+11112223333'
deleted: false,
_id: '61895f552e103829b422e9b5',
company: '61895f55ca365c29b8dea7a6',
updated_at: 1636392789,
created_at: 1636392789,
access_code: '346688',
integrations: []
}
}POST: /v1/connect/contacts/:_id/requestReturns success true and the result of sending the request for documents.
Upon successfully calling this endpoint a contacts "report_status" will be changed to requested. A contact will only be allowed to successfully move through the document portal if their document status is "requested" or "in progress"
Upon signing into the portal their document status is automatically changed to "in progress"
**You may bypass this step by passing the property "request": true when creating a contact.
{
success: true,
message: [],
user_message: [],
api_version: '1.0',
path: 'POST: /v1/connect/contacts/61895f552e103829b422e9b5/request',
time: 1636393740,
milliseconds: 670,
data: {
contact: {
given_name: 'john',
family_name: 'doe',
display_name: 'John Doe',
report_status: 'requested',
email: 'johndoe@gmail.com',
phone: '+11112223333'
deleted: false,
_id: '61895f552e103829b422e9b5',
company: '61895f55ca365c29b8dea7a6',
updated_at: 1636392789,
created_at: 1636392789,
access_code: '346688',
integrations: []
},
event: {
_id: '6189630c6cdbf42a9acfa8cb',
type: 'user',
body: 'A request for documents was sent to the contact via text message and email.',
contact: '6189630c1136642aa363a066',
created_at: 1636393740,
updated_at: 1636393740,
company: '6189630c1136642aa363a065',
__v: 0
},
sentText: true,
sentEmail: true,
}
}GET: /v1/connect/contacts/:_idReturns success true and valid data object if contact was found.
NOTE that this response may return {success: true} without a data field if the _id passed in was not found
{
success: true,
message: [],
user_message: [],
api_version: '1.0',
path: 'GET: /v1/connect/contacts/61895f552e103829b422e9b5',
time: 1636393135,
milliseconds: 196,
data: {
given_name: 'john',
family_name: 'doe',
display_name: 'John Doe',
report_status: 'null',
email: 'johndoe@gmail.com',
phone: '+11112223333'
deleted: false,
_id: '61895f552e103829b422e9b5',
company: '61895f55ca365c29b8dea7a6',
updated_at: 1636392789,
created_at: 1636392789,
access_code: '346688',
integrations: []
}
}GET: /v1/connect/contacts/email/:emailReturns success true and valid data object if contact was found.
NOTE that this response may return {success: true} without a data field if the email passed in was not found
{
success: true,
message: [],
user_message: [],
api_version: '1.0',
path: 'GET: /v1/connect/contacts/email/johndoe@gmail.com',
time: 1636393135,
milliseconds: 196,
data: {
given_name: 'john',
family_name: 'doe',
display_name: 'John Doe',
report_status: 'null',
email: 'johndoe@gmail.com',
phone: '+11112223333'
deleted: false,
_id: '61895f552e103829b422e9b5',
company: '61895f55ca365c29b8dea7a6',
updated_at: 1636392789,
created_at: 1636392789,
access_code: '346688',
integrations: []
}
}GET: /v1/connect/contacts/phone/:phoneReturns success true and valid data object if contact was found.
NOTE that this response may return {success: true} without a data field if the phone passed in was not found
{
success: true,
message: [],
user_message: [],
api_version: '1.0',
path: 'GET: /v1/connect/contacts/phone/+11112223333',
time: 1636393135,
milliseconds: 196,
data: {
given_name: 'john',
family_name: 'doe',
display_name: 'John Doe',
report_status: 'null',
email: 'johndoe@gmail.com',
phone: '+11112223333'
deleted: false,
_id: '61895f552e103829b422e9b5',
company: '61895f55ca365c29b8dea7a6',
updated_at: 1636392789,
created_at: 1636392789,
access_code: '346688',
integrations: []
}
}After a contact links their accounts, documents will be available for download on the dashboard or via webhook (explained below).
They can also be refreshed to get updated information in the form of new documents generated.
POST: /v1/connect/document/refreshReturns success true of false if documents were refreshed.
For convenience contacts can be identified by email, phone, or a Zap Reports contact id.
Note that if searching by email, the identifier sent must be trimmed and in lowercase format.
If searching by phone, the identifier must be in the format +15555555555
** Requests to refresh document are limited to 1 successful request every 24 hours
{
"identifier": "email | phone | id"
}{
"success": true,
"message": [],
"user_message": [],
"api_version": "1.0",
"path": "POST: /v1/connect/documents/refresh",
"time": 1651679424,
"milliseconds": 1269,
"data": {
// how many documents were refreshed
"document_number": 3
}
}{
"success": false,
"user_message": [],
"api_version": "1.0",
"path": "POST: /v1/connect/documents/refresh",
"time": 1651680022,
"milliseconds": 330,
"data": null,
"message": [
"Rate limit exceeded of 1 refresh every 24 hours, this contact can have updated documents requested again at {unix timestamp}"
],
}Webhooks allow your servers to receive information back from Zap Reports as it becomes available.
Currently the Zap Reports API supports the posting of PDF documents back to your servers in a base64 format contained on the property "filedata".
| Property | Type | Values |
|---|---|---|
| name | string | The name of the webhook set up |
| enabled | boolean | If set to false this webhook will not fire. |
| fields | object | {api_endpoint: 'endpoint to send webhooks to'} |
To be able to link documents sent to your servers to the appropriate party Zap Reports supports a custom set of values that can be passed to a contact when they are created.
When Zap Reports sends a webhook to your specified endpoint these values will be passed along with the webhook so you can match the document to the correct party.
{
// base64
filedata: "xlcgoolJUVPRgo=",
// string
filename: "test.pdf",
{
...yourCustomValues
}
}As an example of the entire process, we will start by creating a contact via API with a set of custom values passed along.
The name of the integration should always stay as "documents" to accomodate a standard webhook.
Note the values array sent, this is a set of key value pairs that you can use to send any identifying information you will need to read later on.
** The integrations property is set as an array to accommodate future changes in the API. Currently it supports one object with the name "documents"
POST: /v1/connect/contacts{
given_name: 'John',
family_name: 'Doe',
email: 'johndoe@gmail.com',
phone: '1112223333',
integrations: [{
name: 'documents',
values: {
contact_id: '123'
unique_identifier: 'abc'
}
}]
}Once this contact has linked their accounts, documents will be sent via webhook with the following format.
POST: https://your-server.com/webhooks{
filedata: "xlcgoolJUVPRgo=",
filename: "test.pdf",
contact_id: '123',
unique_identifier: 'abc'
}Post: /v1/connect/webhooksThis endpoint must be called to begin receiving webhooks from Zap Reports to your servers.
Returns success true and information about the endpoint if successful.
Should you ever need to change this webhook in the future see updating a webhook below.
{
"name": "documents",
"api_endpoint": "https://your-server.com/webhooks"
}{
"success": true,
"message": [],
"user_message": [],
"api_version": "1.0",
"path": "POST: /v1/connect/webhooks",
"time": 1645891755,
"milliseconds": 251,
"data": [
{
"name": "documents",
"enabled": true,
"_id": "621a50abb74a9104c69be4e7",
"fields": {
"api_endpoint": "https://your-server.com/webhooks"
}
}
]
}PATH: /v1/connect/webhooksReturns success true and information about the endpoint if successful.
The only fields that can be passed to this endpoint are "enabled" and "api_endpoint".
Should you wish to ever disable a webhook use this endpoint passing {enabled: false} in the body of the request
{
"name": "documents",
"enabled": false,
"api_endpoint": "https://your-server.com/webhooks/v2"
}{
"success": true,
"message": [],
"user_message": [],
"api_version": "1.0",
"path": "POST: /v1/connect/webhooks",
"time": 1645891755,
"milliseconds": 251,
"data": [
{
"name": "documents",
"enabled": false,
"_id": "621a50abb74a9104c69be4e7",
"fields": {
"api_endpoint": "https://your-server.com/webhooks/v2"
}
}
]
}To verify a webhook was sent from Zap Reports all webhooks sent will contain a field called "zap-reports-signature" in the header of the request.
This property should be matched against the Webhook Signing Secret that was displayed when you created or rolled your last set of API keys.
POST: https://your-server.com/webhooks
HEADERS:
{
...
'zap-reports-signature': 'DW6aQptHrlPgUdKdllqzS4UqFmwDBQ',
}
BODY:
{
filedata: "xlcgoolJUVPRgo=",
filename: "test.pdf",
contact_id: '123',
unique_identifier: 'abc'
}
Last Updated: 11/8/2021