API docs by Redocly

Prokeep API (1.1.1)

Download OpenAPI specification:

Prokeep Support: support@prokeep.com License: MIT Terms of Service

Before you can start using the API, API features need to be enabled for your account. If you wish for API features to be enabled for your account, contact your Customer Success representative.

Prokeep's API is protected by Basic Auth over HTTPS. Credentials must be generated in your Prokeep instance's settings. Someone in your organization with "administrator" access must do this. Go to your Prokeep app to get a username and password.

Basic Auth requires an Authorization header, with the credential pair, separated by a colon, encoded in base64. For example, if your username was username and password was password, then your header will contain the encoded value of username:password, which is dXNlcm5hbWU6cGFzc3dvcmQ=. The resulting header would look like this:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Once you have your credentials, you can begin making requests to the Prokeep API.

Making requests

Prokeep's endpoints accept JSON-encoded or XML-encoded requests, and provide JSON-encoded responses. They expect a Content-Type: application/json or Content-Type: application/xml header. They also require the basic auth token covered in the previous section.

As an example, here is a request to Prokeep's Message API to send a message.

$ curl --location --request POST 'https://<subdomain>.prokeep.com/rest/v1/messages' \
> --header 'Content-Type: application/json' \
> --header 'Authorization: Basic bXl1c2VybmFtZTpteXBhc3N3b3Jk' \
> --data-raw '{
>  "from": "+15556667777",
>  "to": "+15557776666",
>  "text": "Hello world!"
> }'
HTTP/1.1 202 Accepted
cache-control: max-age=0, private, must-revalidate
content-encoding: identity
content-length: 7
content-type: application/json; charset=utf-8
date: Thu, 15 Oct 2020 22:42:07 GMT
server: Cowboy
x-request-id: Fj5L-UYbiai2oD4AADaB

{"data":{...}}

The POST should return a 202 Accepted response. This means that Prokeep has queued it for processing.

All endpoints return a JSON object with a data key containing the resource you requested. In case of an error, there will instead be an error key describing the error, like this:

{
  "error": "The 'from' phone number in your request was not valid. Phone numbers must be in E164 format, like +15556667777."
}

TIP: Each request returns an x-request-id header. If you ever encounter problems with specific requests, include this ID in your message to support. That will help us track down the issue.

This documentation uses the domain rest.prokeep.com for all requests, however you should use your specific domain, for example prokeepelectrical.prokeep.com. The path after the domain, /rest/v1, is still required for all requests.

Company

List all companies

This query is paginated, and will not return more than 50 companies at a time.

Authorizations:
prokeep_rest_auth
query Parameters
first
integer <= 50

Controls paging. Will return the first N records in the list, or the first N records before or after a before or after cursor. For example, to fetch the first page of records, use ?first=50.

last
integer <= 50

Controls paging. Will return the last N records in the list, or the last N records before or after a before or after cursor. For example, to fetch the last page of records, use ?last=50.

after
string

Controls paging. This is an opaque cursor that is returned by other requests. Use it in combination with first/last to fetch the next page. For example, after fetching the first page using first, fetch the second page using ?after=<cursor>.

before
string

Controls paging. This is an opaque cursor that is returned by other requests. Use it in combination with first/last to fetch the next page. For example, after fetching the last page using last, fetch the second page using ?before=<cursor>.

group_ids[]
Array of strings <uuid> [ items <uuid > ]
Example: group_ids[]=c09918bc-2093-40cd-922f-58df96ad2ffa&group_ids[]=5e4f32e9-7399-4ad0-98e8-392f57b800ec

The IDs of any groups to filter the companies based on association with those groups.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "has_next_page": true,
  • "has_previous_page": true,
  • "next_cursor": "string",
  • "previous_cursor": "string",
  • "data": [
    ]
}

Create a company

Authorizations:
prokeep_rest_auth
Request Body schema:
optional

The company to create

phone_number
string or null <phone>

The company's primary phone number

name
string or null

The company's name

external_id
string or null

An ID assigned by you to this company

email_address
string or null <email>

The company's primary email address

account_number
string or null

An optional identifier

Responses

Request samples

Content type
{
  • "phone_number": "+12097805965",
  • "name": "American Heating & Cooling",
  • "external_id": "ABC123",
  • "email_address": "user@example.com",
  • "account_number": "ABC123"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Batch create multiple companies at once

Create multiple companies in one request.

Authorizations:
prokeep_rest_auth
Request Body schema:
required

The company parameters, organized as an array of companies to be created. Accepts a batch size of up to 50 companies at a time.

Array of objects (Company)

Responses

Request samples

Content type
{
  • "companies": [
    ]
}

Response samples

Content type
application/json; charset=utf-8
{
  • "companies": [
    ]
}

Get a company

Authorizations:
prokeep_rest_auth
path Parameters
id
required
string
Example: c55817d8-2516-47eb-bf67-f83f52acdfe2

The company ID

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Update a company

Authorizations:
prokeep_rest_auth
path Parameters
id
required
string <uuid>
Example: 7006aa99-7cd9-4dfc-bd35-755fe2d9a6ef

The company to update

Request Body schema:
optional

The company fields to change

phone_number
string or null <phone>

The company's primary phone number

name
string or null

The company's name

external_id
string or null

An ID assigned by you to this company

email_address
string or null <email>

The company's primary email address

account_number
string or null

An optional identifier

Responses

Request samples

Content type
{
  • "phone_number": "+12097805965",
  • "name": "American Heating & Cooling",
  • "external_id": "ABC123",
  • "email_address": "user@example.com",
  • "account_number": "ABC123"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Delete a company

Authorizations:
prokeep_rest_auth
path Parameters
id
required
string <uuid>
Example: b5f3bd31-194d-4fc1-a8a5-b35c2334b0e5

The company to delete

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "errors": [
    ]
}

Get a company by external ID

Authorizations:
prokeep_rest_auth
path Parameters
external_id
required
string
Example: c09918bc-2093-40cd-922f-58df96ad2ffa

The external ID of the company to get

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Contact

List all contacts

This query is paginated, and will not return more than 50 contacts at a time.

Authorizations:
prokeep_rest_auth
query Parameters
first
integer <= 50

Controls paging. Will return the first N records in the list, or the first N records before or after a before or after cursor. For example, to fetch the first page of records, use ?first=50.

last
integer <= 50

Controls paging. Will return the last N records in the list, or the last N records before or after a before or after cursor. For example, to fetch the last page of records, use ?last=50.

after
string

Controls paging. This is an opaque cursor that is returned by other requests. Use it in combination with first/last to fetch the next page. For example, after fetching the first page using first, fetch the second page using ?after=<cursor>.

before
string

Controls paging. This is an opaque cursor that is returned by other requests. Use it in combination with first/last to fetch the next page. For example, after fetching the last page using last, fetch the second page using ?before=<cursor>.

group_ids[]
Array of strings <uuid> [ items <uuid > ]
Example: group_ids[]=c09918bc-2093-40cd-922f-58df96ad2ffa&group_ids[]=5e4f32e9-7399-4ad0-98e8-392f57b800ec

The IDs of any groups to filter the contacts based on association with those groups.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "has_next_page": true,
  • "has_previous_page": true,
  • "next_cursor": "string",
  • "previous_cursor": "string",
  • "data": [
    ]
}

Create a contact

Authorizations:
prokeep_rest_auth
Request Body schema:
optional

The contact parameters

rep_user_id
string <uuid>

The ID of the contact's representative

prioritize_rep
boolean

Whether or not to prioritize notifying this contact's representative before that contact's group

phone_number
string <phone>

The contact's texting phone number

landline
string <phone>

The contact's landline or “Voice-Only Line” phone number

notes
string

Your notepad for this contact

last_name
string

The contact's family name

first_name
string

The contact's given name

external_id
string

An ID assigned by you to this contact

email_address
string <email>

The contact's email address

company_id
string <uuid>

The ID of the company this contact works for

announcements_opt_out
boolean

Whether or not this contact has opted out of Announcements

groups
Array of strings <uuid> [ items <uuid > ]
job_title
string

The contact's job title

fax_opt_out
boolean

Whether or not this contact has opted out of receiving faxes

emails_opt_out
boolean

Whether or not this contact has opted out of receiving emails

api_opt_out
boolean

Whether or not this contact has opted out of receiving api messages

label_ids
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
{
  • "rep_user_id": "7925edf3-849b-4257-b255-473c2089c16d",
  • "prioritize_rep": true,
  • "phone_number": "+15005550001",
  • "landline": "+15005550002",
  • "notes": "Likes the good products, not the bad ones",
  • "last_name": "Garcia",
  • "first_name": "Karen",
  • "external_id": "ABC123",
  • "email_address": "user@example.com",
  • "company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf",
  • "announcements_opt_out": true,
  • "groups": [
    ],
  • "job_title": "string",
  • "fax_opt_out": true,
  • "emails_opt_out": true,
  • "api_opt_out": true,
  • "label_ids": [
    ]
}

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Batch create multiple contacts at once

Create multiple contacts in one request.

Authorizations:
prokeep_rest_auth
Request Body schema:
required

The contact parameters, organized as an array of contacts to be created. Accepts a batch size of up to 50 contacts at a time.

Array of objects (Contact)

Responses

Request samples

Content type
{
  • "contacts": [
    ]
}

Response samples

Content type
application/json; charset=utf-8
{
  • "contacts": [
    ]
}

Get a contact

Authorizations:
prokeep_rest_auth
path Parameters
id
required
string <uuid>
Example: c09918bc-2093-40cd-922f-58df96ad2ffa

The ID of the contact to get

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Update a contact

Authorizations:
prokeep_rest_auth
path Parameters
id
required
string <uuid>
Example: a7086b94-3879-4e2e-859c-ab75109807ab

The ID of the contact to update

Request Body schema:
optional

The contact parameters

rep_user_id
string <uuid>

The ID of the contact's representative

prioritize_rep
boolean

Whether or not to prioritize notifying this contact's representative before that contact's group

phone_number
string <phone>

The contact's texting phone number

landline
string <phone>

The contact's landline or “Voice-Only Line” phone number

notes
string

Your notepad for this contact

last_name
string

The contact's family name

first_name
string

The contact's given name

external_id
string

An ID assigned by you to this contact

email_address
string <email>

The contact's email address

company_id
string <uuid>

The ID of the company this contact works for

announcements_opt_out
boolean

Whether or not this contact has opted out of Announcements

groups
Array of strings <uuid> [ items <uuid > ]
job_title
string

The contact's job title

fax_opt_out
boolean

Whether or not this contact has opted out of receiving faxes

emails_opt_out
boolean

Whether or not this contact has opted out of receiving emails

api_opt_out
boolean

Whether or not this contact has opted out of receiving api messages

label_ids
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
{
  • "rep_user_id": "7925edf3-849b-4257-b255-473c2089c16d",
  • "prioritize_rep": true,
  • "phone_number": "+15005550001",
  • "landline": "+15005550002",
  • "notes": "Likes the good products, not the bad ones",
  • "last_name": "Garcia",
  • "first_name": "Karen",
  • "external_id": "ABC123",
  • "email_address": "user@example.com",
  • "company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf",
  • "announcements_opt_out": true,
  • "groups": [
    ],
  • "job_title": "string",
  • "fax_opt_out": true,
  • "emails_opt_out": true,
  • "api_opt_out": true,
  • "label_ids": [
    ]
}

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Delete a contact

Authorizations:
prokeep_rest_auth
path Parameters
id
required
string <uuid>
Example: 10f5d67a-93d3-4906-8478-187f1a9abf24

The ID of the contact to delete

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "errors": [
    ]
}

Get a contact by external ID

Authorizations:
prokeep_rest_auth
path Parameters
external_id
required
string
Example: c09918bc-2093-40cd-922f-58df96ad2ffa

The external ID of the contact to get

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Emails

Send an email

Authorizations:
prokeep_rest_auth
Request Body schema:
required

The message details

Array of objects

URLs to attachments to include in the email

body
required
string

The body of the email

from
required
string <email>

The email address to the email is to be sent from

subject
required
string

The subject line of the email

tags
Array of strings

One or more keywords to categorize and reference the message.

to
required
string <email>

The email address to send the email to

Responses

Request samples

Content type
{}

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Group

List all of this account's groups

Authorizations:
prokeep_rest_auth

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": [
    ]
}

Paginate account's groups

Authorizations:
prokeep_rest_auth
query Parameters
after
string

Controls paging. This is an opaque cursor that is returned by other requests. Used to return pages occuring after the cursor.

before
string

Controls paging. This is an opaque cursor that is returned by other requests. Used to return pages occuring before the cursor.

limit
integer <= 50

The maximum count of items to include in the response.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": [
    ],
  • "page_info": {
    }
}

Order Status Updates

List all orders statuses for an account

This query is paginated, and will not return more than 50 orders at a time.

Authorizations:
prokeep_rest_auth
query Parameters
first
integer <= 50

Controls paging. Will return the first N records in the list, or the first N records before or after a before or after cursor. For example, to fetch the first page of records, use ?first=50.

last
integer <= 50

Controls paging. Will return the last N records in the list, or the last N records before or after a before or after cursor. For example, to fetch the last page of records, use ?last=50.

after
string

Controls paging. This is an opaque cursor that is returned by other requests. Use it in combination with first/last to fetch the next page. For example, after fetching the first page using first, fetch the second page using ?after=<cursor>.

before
string

Controls paging. This is an opaque cursor that is returned by other requests. Use it in combination with first/last to fetch the next page. For example, after fetching the last page using last, fetch the second page using ?before=<cursor>.

external_id
string <uuid>
Example: external_id=c09918bc-2093-40cd-922f-58df96ad2ffa

The external ID of any order to filter the order statuses based on association with said order.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "has_next_page": true,
  • "has_previous_page": true,
  • "next_cursor": "string",
  • "previous_cursor": "string",
  • "data": [
    ]
}

List all orders statuses for an order

This query is paginated, and will not return more than 50 orders at a time.

Authorizations:
prokeep_rest_auth
path Parameters
order_id
string <uuid>
Example: c09918bc-2093-40cd-922f-58df96ad2ffa

The ID of any order to filter the order statuses based on association with said order.

query Parameters
first
integer <= 50

Controls paging. Will return the first N records in the list, or the first N records before or after a before or after cursor. For example, to fetch the first page of records, use ?first=50.

last
integer <= 50

Controls paging. Will return the last N records in the list, or the last N records before or after a before or after cursor. For example, to fetch the last page of records, use ?last=50.

after
string

Controls paging. This is an opaque cursor that is returned by other requests. Use it in combination with first/last to fetch the next page. For example, after fetching the first page using first, fetch the second page using ?after=<cursor>.

before
string

Controls paging. This is an opaque cursor that is returned by other requests. Use it in combination with first/last to fetch the next page. For example, after fetching the last page using last, fetch the second page using ?before=<cursor>.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "has_next_page": true,
  • "has_previous_page": true,
  • "next_cursor": "string",
  • "previous_cursor": "string",
  • "data": [
    ]
}

Create a status for an order

Authorizations:
prokeep_rest_auth
path Parameters
order_id
string <uuid>
Example: c09918bc-2093-40cd-922f-58df96ad2ffa

The ID of any order to filter the order statuses based on association with said order.

Request Body schema:
optional

The order status update parameters. Accepts an addtional 'true' or 'false' 'send_notifications' parameter that sends an automated sms to the contacts associated with the order status's order.

status
string

The order status of the order

order_id
string <uuid>

The ID of the account that is associated with this order

Responses

Request samples

Content type
{
  • "status": "Order Received",
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Get an order status for an order

Authorizations:
prokeep_rest_auth
path Parameters
order_id
string <uuid>
Example: c09918bc-2093-40cd-922f-58df96ad2ffa

The ID of any order to filter the order statuses based on association with said order.

id
required
string <uuid>
Example: c09918bc-2093-40cd-922f-58df96ad2ffa

The ID of the order status to get

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Order

List all orders

This query is paginated, and will not return more than 50 orders at a time.

Authorizations:
prokeep_rest_auth
query Parameters
first
integer <= 50

Controls paging. Will return the first N records in the list, or the first N records before or after a before or after cursor. For example, to fetch the first page of records, use ?first=50.

last
integer <= 50

Controls paging. Will return the last N records in the list, or the last N records before or after a before or after cursor. For example, to fetch the last page of records, use ?last=50.

after
string

Controls paging. This is an opaque cursor that is returned by other requests. Use it in combination with first/last to fetch the next page. For example, after fetching the first page using first, fetch the second page using ?after=<cursor>.

before
string

Controls paging. This is an opaque cursor that is returned by other requests. Use it in combination with first/last to fetch the next page. For example, after fetching the last page using last, fetch the second page using ?before=<cursor>.

group_id
string <uuid>
Example: group_id=c09918bc-2093-40cd-922f-58df96ad2ffa

The ID of any group to filter the orders based on association with said group.

company_id
string <uuid>
Example: company_id=c09918bc-2093-40cd-922f-58df96ad2ffa

The ID of any company to filter the orders based on association with said company.

address
string <address line 1, address line 2 (optional), city, state abbr, postal code>
Example: address=1234 NW Bobcat Lane, apt. 23, St. Robert, MO, 65584, US

The address to filter the orders based on association with said address.

contact_ids[]
Array of strings <uuid> [ items <uuid > ]
Example: contact_ids[]=c09918bc-2093-40cd-922f-58df96ad2ffa&contact_ids[]=5e4f32e9-7399-4ad0-98e8-392f57b800ec

The IDs of any contact to filter the orders based on association with said contact.

order_ids[]
Array of strings <uuid> [ items <uuid > ]
Example: order_ids[]=c09918bc-2093-40cd-922f-58df96ad2ffa&order_ids[]=5e4f32e9-7399-4ad0-98e8-392f57b800ec

The IDs of orders to filter the orders on.

order_type_filter
string
Enum: "pick_up" "ship"
Example: order_type_filter=pick_up

The order type to filter the orders on.

order_status_filter
string
Example: order_status_filter=Ready for Pick Up

The order status to filter the orders on.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "has_next_page": true,
  • "has_previous_page": true,
  • "next_cursor": "string",
  • "previous_cursor": "string",
  • "data": [
    ]
}

Create an order

Authorizations:
prokeep_rest_auth
Request Body schema:
optional

The order parameters.

order_number
string

The order number of the order

external_id
string

An ID assigned by you to this order

amount
string <#,###.##>

The total monetary amount of the order. The accepted input formats are '$##,###.##', '##,###.##', '$#,###', or '#,###'. Please note in the case of '$#,###', or '#,###' it will be assumed there is '00' cents.

currency
string

The currency associated with the total amount of the order

order_type
string

An enum representing the type of order. Can be either 'pick_up' or 'ship'.

account_id
string <uuid>

The ID of the account that is associated with this order

group_id
string <uuid>

The ID of the group that is associated with this order

company_id
string <uuid>

The ID of the company that is associated with this order

address
string <address line 1, address line 2 (optional), city, state abbr, postal code, country code (optional)>

The address that is associated with this order. Please note that the country code defaults to 'US'.

order_status
string

The most recent order status associated with this order

contact_ids
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
{
  • "order_number": "123456789ZA",
  • "external_id": "ABC123",
  • "amount": "73.12",
  • "currency": "USD",
  • "order_type": "pick_up",
  • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
  • "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  • "company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf",
  • "address": "1234 NW Bobcat Lane, St. Robert, MO, 65584, US",
  • "order_status": "Order Being Prepared",
  • "contact_ids": [
    ]
}

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Get an order

Authorizations:
prokeep_rest_auth
path Parameters
id
required
string <uuid>
Example: c09918bc-2093-40cd-922f-58df96ad2ffa

The ID of the order to get

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Update an order

Authorizations:
prokeep_rest_auth
path Parameters
id
required
string <uuid>
Example: a7086b94-3879-4e2e-859c-ab75109807ab

The ID of the order to update

Request Body schema:
optional

The order parameters.

order_number
string

The order number of the order

external_id
string

An ID assigned by you to this order

amount
string <#,###.##>

The total monetary amount of the order. The accepted input formats are '$##,###.##', '##,###.##', '$#,###', or '#,###'. Please note in the case of '$#,###', or '#,###' it will be assumed there is '00' cents.

currency
string

The currency associated with the total amount of the order

order_type
string

An enum representing the type of order. Can be either 'pick_up' or 'ship'.

account_id
string <uuid>

The ID of the account that is associated with this order

group_id
string <uuid>

The ID of the group that is associated with this order

company_id
string <uuid>

The ID of the company that is associated with this order

address
string <address line 1, address line 2 (optional), city, state abbr, postal code, country code (optional)>

The address that is associated with this order. Please note that the country code defaults to 'US'.

order_status
string

The most recent order status associated with this order

contact_ids
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
{
  • "order_number": "123456789ZA",
  • "external_id": "ABC123",
  • "amount": "73.12",
  • "currency": "USD",
  • "order_type": "pick_up",
  • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
  • "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  • "company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf",
  • "address": "1234 NW Bobcat Lane, St. Robert, MO, 65584, US",
  • "order_status": "Order Being Prepared",
  • "contact_ids": [
    ]
}

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Delete a order

Authorizations:
prokeep_rest_auth
path Parameters
id
required
string <uuid>
Example: 10f5d67a-93d3-4906-8478-187f1a9abf24

The ID of the order to delete

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "errors": [
    ]
}

Order Status Update

Update the status of an order status update

Authorizations:
prokeep_rest_auth
path Parameters
order_id
required
string <uuid>
Example: a7086b94-3879-4e2e-859c-ab75109807ab

The order ID of the order status update to update

id
required
string <uuid>
Example: a7086b94-3879-4e2e-859c-ab75109807ab

The ID of the order status update to update

Request Body schema:
optional

This endpoint only accepts “status” as a parameter and nothing else. If “status” is not in the body, then an error is returned. This would be an endpoint for a user who would want to edit a specific order_status_update’s status because of a typo or something. If a user wants to update the status of an order then these users would either use the POST "rest/v1/orders/:order_id/status_updates" endpoint which has the optional “send_notification” functionality or they can update the “order_status” field of an order using the PUT “rest/v1/orders/:order_id” endpoint (this second method does not have notification functionality).

status
string

The order status of the order

order_id
string <uuid>

The ID of the account that is associated with this order

Responses

Request samples

Content type
{
  • "status": "Order Received",
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Delete an order status for an order

Authorizations:
prokeep_rest_auth
path Parameters
order_id
required
string <uuid>
Example: a7086b94-3879-4e2e-859c-ab75109807ab

The order ID of the order status update to delete

id
required
string <uuid>
Example: a7086b94-3879-4e2e-859c-ab75109807ab

The ID of the order status update to delete

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "errors": [
    ]
}

Users

List users

This query is paginated, and will not return more than 50 users at a time.

Authorizations:
prokeep_rest_auth
query Parameters
after
string

Controls paging. This is an opaque cursor that is returned by other requests. Used to return pages occuring after the cursor.

before
string

Controls paging. This is an opaque cursor that is returned by other requests. Used to return pages occuring before the cursor.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "page_info": {
    },
  • "edges": [
    ]
}

Messages

Send a message

In order to send a message successfully, the following requirements must be met:

  1. The from number must belong to your account
  2. Both the from and to phone numbers must be in E164 format, for example +15556667777

Once the message is sent, it will appear on the Prokeep app as a normal message. If you had no previous open thread with that contact, the thread will be archived automatically. If the contact responds, the message will appear in your Prokeep inbox as it normally would.

If you want to be able to react to incoming messages, see the section on Webhooks.

Authorizations:
prokeep_rest_auth
Request Body schema:
optional

The message details

text
required
string

The text of the message

from
required
string <phone>

The phone number to send the message from

required
string or string or string

The recipient, either a contact's phone number, contact_id or external_id

status_callback
string <uri>

The URL we should call to send status information about this message to your application. The message statuses that will be received from this status callback are sent or failed.

Array of objects or objects

URLs to attachments to include with the message

tags
Array of strings

One or more keywords to categorize and reference the message.

Responses

Request samples

Content type
{}

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Send an internal message

Sends a message to a group's inbox, creating a new internal thread. Internal messages are visible only within your Prokeep account and are not delivered to external contacts.

Once sent, the message will appear in the specified group's inbox as a normal internal thread.

Authorizations:
prokeep_rest_auth
Request Body schema: application/json; charset=utf-8
optional

The internal message details

group_id
required
string <uuid>

The ID of the group inbox to send the message to.

text
required
string [ 1 .. 10000 ] characters

The text content of the message (1–10,000 characters).

Array of objects or objects

Attachments to include with the message.

additional_user_ids
Array of strings <uuid> [ items <uuid > ]

Additional user IDs to include in the internal thread, beyond the sender.

tags
Array of strings

One or more work order reference numbers to associate with this message.

Array of objects

Structured work orders to associate with this message. Use this instead of tags when you need to specify the source system.

object

Template metadata for tracking purposes.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "group_id": "d14c3097-f405-4ac0-8c39-e7ac38b33074",
  • "text": "Heads up — order",
  • "attachments": [],
  • "additional_user_ids": [
    ],
  • "tags": [
    ],
  • "work_orders": [
    ],
  • "template": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Thread

List threads

Returns a paginated list of threads for the account. Each thread includes its most recent message.

Threads can be filtered by status, group, owner, or date range. By default, all threads accessible to the authenticated user are returned.

Authorizations:
prokeep_rest_auth
query Parameters
first
integer <= 50

Controls paging. Will return the first N records in the list, or the first N records before or after a before or after cursor. For example, to fetch the first page of records, use ?first=50.

after
string

Controls paging. This is an opaque cursor that is returned by other requests. Use it in combination with first/last to fetch the next page. For example, after fetching the first page using first, fetch the second page using ?after=<cursor>.

before
string

Controls paging. This is an opaque cursor that is returned by other requests. Use it in combination with first/last to fetch the next page. For example, after fetching the last page using last, fetch the second page using ?before=<cursor>.

status
string
Enum: "unclaimed" "active" "archived"

Filter threads by a single status.

statuses[]
Array of strings
Items Enum: "unclaimed" "active" "archived"

Filter threads by multiple statuses.

group_id
string <uuid>

Filter threads belonging to a single group.

group_ids[]
Array of strings <uuid> [ items <uuid > ]

Filter threads belonging to any of the specified groups.

owner_contact_id
string <uuid>

Filter threads owned by a specific contact.

start_date
string <date-time>
Example: start_date=2024-01-01T00:00:00Z

Return only threads created at or after this date (ISO8601).

end_date
string <date-time>
Example: end_date=2024-12-31T23:59:59Z

Return only threads created at or before this date (ISO8601).

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "has_next_page": true,
  • "has_previous_page": true,
  • "next_cursor": "string",
  • "previous_cursor": "string",
  • "data": [
    ]
}

Get a thread

Returns a single thread by ID, including its full message history ordered chronologically.

Authorizations:
prokeep_rest_auth
path Parameters
id
required
string <uuid>

The ID of the thread.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Label

List all labels

Returns all labels configured for the account.

Authorizations:
prokeep_rest_auth

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": [
    ]
}

Webhook

Get all webhooks

Get all the webhooks configured for your account.

Authorizations:
prokeep_rest_auth

Responses

Response samples

Content type
application/json; charset=utf-8
{}

Create webhook

Create a new webhook, which will tell Prokeep to send a POST request to a given URL when certain events occur.

Once you've created a webhook, expect to see HTTP requests against the given URL. Prokeep webhook payloads follow the CloudEvents 1.0 spec. Each request will have a Content-Type: application/cloudevents+json header and a JSON body containing the CloudEvents envelope fields along with the data that triggered the event.

For example, create a webhook to see all incoming messages, and you'll see a request like this:

{
  "specversion": "1.0",
  "id": "a8f3c2d1-4b7e-4f9a-b2c3-1d2e3f4a5b6c",
  "source": "https://prokeep.com",
  "type": "message_received",
  "event": "message_received",
  "data": {
    "id": "12345",
    "thread_id": "67890",
    "text": "Hello callback!"
  }
}

The event field is a deprecated alias for type and is included for backwards compatibility.

Authorizations:
prokeep_rest_auth
Request Body schema:
optional

The webhook details

url
required
string <uri>

A URL that receives events as HTTP POST requests

Array of objects (WebhookHeader)

An array of header values that will be included with every webhook request.

event_thread_created
boolean

Fire the webhook when a thread is created, with the event type "thread_created"

event_thread_closed
boolean

Fire the webhook when a thread is closed, with the event type "thread_closed"

event_thread_claimed
boolean

Fire the webhook when a thread is claimed, with the event type "thread_claimed"

event_message_sent
boolean

Fire the webhook when a message is sent, with the event type "message_sent"

event_message_received
boolean

Fire the webhook when a message is received, with the event type "message_received"

event_contact_updated
boolean

Fire the webhook when a contact is updated, with the event type "contact_updated"

event_contact_created
boolean

Fire the webhook when a contact is created, with the event type "contact_created"

event_company_updated
boolean

Fire the webhook when a contact company is updated, with the event type "company_updated"

event_company_created
boolean

Fire the webhook when a contact company is created, with the event type "company_created"

Responses

Callbacks

Request samples

Content type
{}

Response samples

Content type
application/json; charset=utf-8
{}

Callback payload samples

Callback
Content type
application/cloudevents+json
{
  • "specversion": "1.0",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "source": "https://prokeep.com",
  • "type": "company_created",
  • "event": "company_created",
  • "data": {
    }
}

Get a webhook

Get a webhook by ID

Authorizations:
prokeep_rest_auth
path Parameters
id
required
string <uuid>
Example: 29a6807f-921c-4918-a4d7-cec9d265de23

The webhook ID

Responses

Response samples

Content type
application/json; charset=utf-8
{}

Update a webhook

Authorizations:
prokeep_rest_auth
path Parameters
id
required
string <uuid>
Example: d5efe91e-b609-4764-8520-1c05c51a8438

The webhook ID

Request Body schema:

The webhook fields you wish to change

url
required
string <uri>

A URL that receives events as HTTP POST requests

Array of objects (WebhookHeader)

An array of header values that will be included with every webhook request.

event_thread_created
boolean

Fire the webhook when a thread is created, with the event type "thread_created"

event_thread_closed
boolean

Fire the webhook when a thread is closed, with the event type "thread_closed"

event_thread_claimed
boolean

Fire the webhook when a thread is claimed, with the event type "thread_claimed"

event_message_sent
boolean

Fire the webhook when a message is sent, with the event type "message_sent"

event_message_received
boolean

Fire the webhook when a message is received, with the event type "message_received"

event_contact_updated
boolean

Fire the webhook when a contact is updated, with the event type "contact_updated"

event_contact_created
boolean

Fire the webhook when a contact is created, with the event type "contact_created"

event_company_updated
boolean

Fire the webhook when a contact company is updated, with the event type "company_updated"

event_company_created
boolean

Fire the webhook when a contact company is created, with the event type "company_created"

Responses

Request samples

Content type
{}

Response samples

Content type
application/json; charset=utf-8
{}

Delete a webhook

Authorizations:
prokeep_rest_auth
path Parameters
id
required
string <uuid>
Example: 12b8c68-3051-4f7f-923a-f573919b3145

The webhook ID

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "errors": [
    ]
}