API docs by Redocly

GoCXL API (1.0.1)

Download OpenAPI specification:Download

URL: https://gocxl.com

This document describes the GoCXL API server.

Pagination

If the endpoint requested supports pagination, you can check the Response Headers inside the 200 response to see how you can paginate the results.

API::V1::Accounts

Retrieve an existing account

To show information about an account, send a GET request to /api/v1/accounts/$ACCOUNT_ID.

Authorizations:
oauth
path Parameters
account_id
required
string <uuid>
Example: acf19357-d974-4843-9525-e98426ad5346

A unique identifier for an account.

Responses

Response samples

Content type
application/json
{
  • "account": {
    }
}

API::V1::Categories

List all categories

To list all categories in your account, send a GET request to /api/v1/categories.

The response body will be a JSON object with a key of categories. This will be set to an array containing objects each representing a category.

Authorizations:
oauth
query Parameters
slug
string
Example: slug=insurances

Used to filter categories by a specific slug.

locales[]
Array of strings
Example: locales[]=nl-NL

Used to filter categories by specific locales.

object

Used to order categories by created_at and/or name. Example: sort[created_at]=asc&sort[name]=desc

cursor
string

The requested cursor token for paginated responses.

limit
integer
Default: 20

The requested amount of items for paginated responses.

object

Used to filter by account metadata. Example: metadata[key[subkey]]=value

Responses

Response samples

Content type
application/json
{
  • "categories": [
    ]
}

Retrieve an existing category

To show information about a category, send a GET request to /api/v1/categories/$CATEGORY_ID.

Authorizations:
oauth
path Parameters
category_id
required
string <uuid>
Example: dff66101-e1da-4e93-bad0-12908a8be91d

A unique identifier for a category.

Responses

Response samples

Content type
application/json
{
  • "category": {
    }
}

List all organizations of a category

To list all organizations in your account, send a GET request to /api/v1/$CATEGORY_ID/organizations.

The response body will be a JSON object with a key of organizations. This will be set to an array containing objects each representing a organization.

Authorizations:
oauth
path Parameters
category_id
required
string <uuid>
Example: dff66101-e1da-4e93-bad0-12908a8be91d

A unique identifier for a category.

query Parameters
object

Used to order organizations by created_at and/or name. Example: sort[created_at]=desc&sort[name]=asc

cursor
string

The requested cursor token for paginated responses.

limit
integer
Default: 20

The requested amount of items for paginated responses.

object

Used to filter by account metadata. Example: metadata[key[subkey]]=value

Responses

Response samples

Content type
application/json
{
  • "organizations": [
    ]
}

API::V1::DispatchableEvents

Retrieve an existing letter event

To show information about a letter event, send a GET request to /api/v1/letter_events/$LETTER_EVENT_ID.

Authorizations:
oauth
path Parameters
letter_event_id
required
string <uuid>
Example: 459a5993-1560-44bd-b879-258075b77e13

A unique identifier for a letter event.

Responses

Response samples

Content type
application/json
{
  • "letter_event": {
    }
}

API::V1::Letters

List all letters

To list all letters in your account, send a GET request to /api/v1/letters.

The response body will be a JSON object with a key of letters. This will be set to an array containing objects each representing a letter.

Authorizations:
oauth
query Parameters
object

Used to order letters by created_at. Example: sort[created_at]=asc

cursor
string

The requested cursor token for paginated responses.

limit
integer
Default: 20

The requested amount of items for paginated responses.

object

Used to filter by account metadata. Example: metadata[key[subkey]]=value

Responses

Response samples

Content type
application/json
{
  • "letters": [
    ]
}

Create a new letter

Create a new letter by submitting the parameters required by the template to POST /api/v1/letters.

Authorizations:
oauth
Request Body schema: application/json
organization_id
required
string <uuid>

A string specifying the UUID of the organization the letter is intended for.

product_id
string <uuid>

An optional string specifying the UUID of the product the letter is intended for.

provider_id
string <uuid>

A string specifying the UUID of the provider to use when sending the letter.

locale
required
string

The locale of the letter.

signature_type
string

The type of signature (could be text or image)

signature_data
string

The data for the signature. Will be the name for signature_type text and the base64 encode string for signature_type image

required
object

The parameters to use when generating the letter as described by the fields of the organization's or product's letter template.

consent
boolean or null

A boolean indicating if the user gave explicit consent to create the letter request. Only required when either the organization or products requires so.

proof_of_ids
Array of strings

An array of ID documents as base64 encoded blobs.

metadata
object

An optional set of key-value pairs that are attached for your account. Please note that:

  • Keys can only contain a-z (lowercase), - and _ with a max length of 255
  • Each value for a key can not be more than 100Kb
drafted
boolean

We can go directly to the state drafted by passing a true value to this parameter

Responses

Request samples

Content type
application/json
{
  • "organization_id": "20ab8e7e-8d51-4144-b92a-03af909a6895",
  • "product_id": "bfc501cf-dc45-40ca-aba3-b05018c8f8be",
  • "provider_id": "20ab8e7e-8d51-4144-b92a-03af909a6895",
  • "locale": "nl-NL",
  • "signature_type": "text",
  • "signature_data": "John Doe",
  • "parameters": {
    },
  • "consent": true,
  • "proof_of_ids": [
    ],
  • "metadata": { },
  • "drafted": true
}

Response samples

Content type
application/json
{
  • "letter": {
    }
}

Retrieve an existing letter

To show information about a letter, send a GET request to /api/v1/letters/$LETTER_ID.

Authorizations:
oauth
path Parameters
letter_id
required
string <uuid>
Example: 87ed0487-7e18-4380-9028-3d7fd2c46433

A unique identifier for a letter.

Responses

Response samples

Content type
application/json
{
  • "letter": {
    }
}

Update a existing letter

Update a existing letter by submitting the parameters required by the template to PUT or PATCH /api/v1/letters/$LETTER_ID.

Letter is required to be in the state drafting.

Authorizations:
oauth
path Parameters
letter_id
required
string <uuid>
Example: 87ed0487-7e18-4380-9028-3d7fd2c46433

A unique identifier for a letter.

Request Body schema: application/json
organization_id
required
string <uuid>

A string specifying the UUID of the organization the letter is intended for.

product_id
string <uuid>

An optional string specifying the UUID of the product the letter is intended for.

provider_id
string <uuid>

A string specifying the UUID of the provider to use when sending the letter.

locale
required
string

The locale of the letter.

signature_type
string

The type of signature (could be text or image)

signature_data
string

The data for the signature. Will be the name for signature_type text and the base64 encode string for signature_type image

required
object

The parameters to use when generating the letter as described by the fields of the organization's or product's letter template.

consent
boolean or null

A boolean indicating if the user gave explicit consent to create the letter request. Only required when either the organization or products requires so.

proof_of_ids
Array of strings

An array of ID documents as base64 encoded blobs.

metadata
object

An optional set of key-value pairs that are attached for your account. Please note that:

  • Keys can only contain a-z (lowercase), - and _ with a max length of 255
  • Each value for a key can not be more than 100Kb
drafted
boolean

We can go directly to the state drafted by passing a true value to this parameter

Responses

Request samples

Content type
application/json
{
  • "organization_id": "20ab8e7e-8d51-4144-b92a-03af909a6895",
  • "product_id": "bfc501cf-dc45-40ca-aba3-b05018c8f8be",
  • "provider_id": "20ab8e7e-8d51-4144-b92a-03af909a6895",
  • "locale": "nl-NL",
  • "signature_type": "text",
  • "signature_data": "John Doe",
  • "parameters": {
    },
  • "consent": true,
  • "proof_of_ids": [
    ],
  • "metadata": { },
  • "drafted": true
}

Response samples

Content type
application/json
{
  • "letter": {
    }
}

Delete an existing letter

To delete a letter, send a DELETE request to /api/v1/letters/$LETTER_ID.

This operation is only allowed for sandboxed accounts.

Authorizations:
oauth
path Parameters
letter_id
required
string <uuid>
Example: 87ed0487-7e18-4380-9028-3d7fd2c46433

A unique identifier for a letter.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Retrieve document for an existing letters

To download the generated document for a letter, send a GET request to /api/v1/letters/$LETTER_ID/document.

The response body will be a binary stream containing the document.

Authorizations:
oauth
path Parameters
letter_id
required
string <uuid>
Example: 87ed0487-7e18-4380-9028-3d7fd2c46433

A unique identifier for a letter.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Generate a PDF document from a letter payload

To generate a document from a letter payload and download it, send a POST request with payload to /api/v1/generate_pdf.

The response body will be a binary stream containing the document.

Authorizations:
oauth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "letter": {
    }
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Mark letter as drafted

Updates the letter to the new state.

Authorizations:
oauth
path Parameters
letter_id
required
string <uuid>
Example: 87ed0487-7e18-4380-9028-3d7fd2c46433

A unique identifier for a letter.

Request Body schema: application/json
provider_key
string
metadata
object

A set of key-value pairs that are attached to the Letter event object.

Responses

Request samples

Content type
application/json
{
  • "provider_key": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "letter": {
    }
}

List all letter events

To list all letter events in your account, send a GET request to /api/v1/letters/$LETTER_ID/events.

The response body will be a JSON object with a key of events. This will be set to an array containing objects each representing a letter event.

Authorizations:
oauth
path Parameters
letter_id
required
string <uuid>
Example: 87ed0487-7e18-4380-9028-3d7fd2c46433

A unique identifier for a letter.

query Parameters
object

Used to order letter_events by received_at. Example: sort[received_at]=asc

cursor
string

The requested cursor token for paginated responses.

limit
integer
Default: 20

The requested amount of items for paginated responses.

Responses

Response samples

Content type
application/json
{
  • "letter_events": [
    ]
}

Download an uploaded proof of ID

To download a proof of ID for a letter, send a GET request to /api/v1/letters/$LETTER_ID/proof_of_ids/$PROOF_OF_ID_ID.

The response body will be a binary stream containing the uploaded proof of ID.

Authorizations:
oauth
path Parameters
letter_id
required
string <uuid>
Example: 87ed0487-7e18-4380-9028-3d7fd2c46433

A unique identifier for a letter.

proof_of_id_id
required
string <uuid>
Example: 459a5993-1560-44bd-b879-258075b77e13

A unique identifier for an uploaded proof of ID.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

API::V1::Organizations

List all organizations

To list all organizations in your account, send a GET request to /api/v1/organizations.

The response body will be a JSON object with a key of organizations. This will be set to an array containing objects each representing a organization.

Authorizations:
oauth
query Parameters
slug
string
Example: slug=allianz-nederland

Used to filter organizations by a specific slug.

category
string
Example: category=insurances

Used to filter organizations by a specific category.

locales[]
Array of strings
Example: locales[]=nl-NL

Used to filter organizations by specific locales.

url
string
Example: url=allianz.nl

Used to filter organizations by a (partial) URL.

object

Used to order organizations by created_at and/or name. Example: sort[created_at]=desc&sort[name]=asc

cursor
string

The requested cursor token for paginated responses.

limit
integer
Default: 20

The requested amount of items for paginated responses.

object

Used to filter by account metadata. Example: metadata[key[subkey]]=value

Responses

Response samples

Content type
application/json
{
  • "organizations": [
    ]
}

Retrieve an existing organization

To show information about an organization, send a GET request to /api/v1/organizations/$ORGANIZATION_ID.

Authorizations:
oauth
path Parameters
organization_id
required
string <uuid>
Example: 0df21c85-54f5-4ce9-be17-4a2fb63e958c

A unique identifier for an organization.

Responses

Response samples

Content type
application/json
{
  • "organization": {
    }
}

List all products of an organization.

To list all products for an organizations in your account, send a GET request to /api/v1/organizations/$ORGANIZATION_ID/products.

The response body will be a JSON object with a key of products. This will be set to an array containing objects each representing a product.

Authorizations:
oauth
path Parameters
organization_id
required
string <uuid>
Example: 0df21c85-54f5-4ce9-be17-4a2fb63e958c

A unique identifier for an organization.

query Parameters
slug
string
Example: slug=liability-insurance

Used to filter products by a specific slug.

locales[]
Array of strings
Example: locales[]=nl-NL

Used to filter products by specific locales.

url
string
Example: url=allianz.nl

Used to filter products by a (partial) URL.

object

Used to order products by created_at and/or name. Example: sort[created_at]=desc&sort[name]=asc

cursor
string

The requested cursor token for paginated responses.

limit
integer
Default: 20

The requested amount of items for paginated responses.

object

Used to filter by account metadata. Example: metadata[key[subkey]]=value

Responses

Response samples

Content type
application/json
{
  • "products": [
    ]
}

Search for organizations or products

To find Organizations or Products matching the search string, send a GET request to /api/v1/search.

Authorizations:
oauth
query Parameters
q
string

The input that needs to be searched for

record_type
string
Example: record_type=product

Used to filter results by their type. Possible options are 'organization' or 'product'.

locale
string
Example: locale=nl-NL

Used to filter results by their locale.

cursor
string

The requested cursor token for paginated responses.

limit
integer
Default: 20

The requested amount of items for paginated responses.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

API::V1::Products

Retrieve an existing product for an organization

To show information about an organization's product, send a GET request to /api/v1/organizations/$ORGANIZATION_ID/products/$PRODUCT_ID.

Authorizations:
oauth
path Parameters
organization_id
required
string <uuid>
Example: 0df21c85-54f5-4ce9-be17-4a2fb63e958c

A unique identifier for an organization.

product_id
required
string
Example: bfc501cf-dc45-40ca-aba3-b05018c8f8be

A unique identifier for an organization's product.

Responses

Response samples

Content type
application/json
{
  • "product": {
    }
}

Retrieve an generic product for an organization

To show information about an organization's generic product, send a GET request to /api/v1/organizations/$ORGANIZATION_ID/products/generic.

Authorizations:
oauth
path Parameters
organization_id
required
string <uuid>
Example: 0df21c85-54f5-4ce9-be17-4a2fb63e958c

A unique identifier for an organization.

Responses

Response samples

Content type
application/json
{
  • "product": {
    }
}

Retrieve an existing product

To show information about an product, send a GET request to /api/v1/products/$PRODUCT_ID.

Authorizations:
oauth
path Parameters
product_id
required
string
Example: bfc501cf-dc45-40ca-aba3-b05018c8f8be

A unique identifier for an organization's product.

Responses

Response samples

Content type
application/json
{
  • "product": {
    }
}

Search for organizations or products

To find Organizations or Products matching the search string, send a GET request to /api/v1/search.

Authorizations:
oauth
query Parameters
q
string

The input that needs to be searched for

record_type
string
Example: record_type=product

Used to filter results by their type. Possible options are 'organization' or 'product'.

locale
string
Example: locale=nl-NL

Used to filter results by their locale.

cursor
string

The requested cursor token for paginated responses.

limit
integer
Default: 20

The requested amount of items for paginated responses.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

API::V1::Providers

List all providers

To list all providers in your account, send a GET request to /api/v1/providers.

The response body will be a JSON object with a key of providers. This will be set to an array containing objects each representing a provider.

Authorizations:
oauth
query Parameters
object

Used to order providers by created_at, name, provider_type and/or type. Example: sort[created_at]=desc&sort[name]=asc

cursor
string

The requested cursor token for paginated responses.

limit
integer
Default: 20

The requested amount of items for paginated responses.

Responses

Response samples

Content type
application/json
{
  • "providers": [
    ]
}

Retrieve an existing provider

To show information about a provider, send a GET request to /api/v1/providers/$PROVIDER_ID.

Authorizations:
oauth
path Parameters
provider_id
required
string <uuid>
Example: 05926e22-152d-484e-b4b7-73928d829350

A unique identifier for a provider.

Responses

Response samples

Content type
application/json
{
  • "provider": {
    }
}

API::V1::Searches

Search for organizations or products

To find Organizations or Products matching the search string, send a GET request to /api/v1/search.

Authorizations:
oauth
query Parameters
q
string

The input that needs to be searched for

record_type
string
Example: record_type=product

Used to filter results by their type. Possible options are 'organization' or 'product'.

locale
string
Example: locale=nl-NL

Used to filter results by their locale.

cursor
string

The requested cursor token for paginated responses.

limit
integer
Default: 20

The requested amount of items for paginated responses.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

API::V1::Webhooks

GoCXL uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when a letter gets sent to an organization, or when an organization receives a cancellation letter.

Validate the webhook signatures

GoCXL signs the webhook events we send to your endpoints by including a signature in each event's Gocxl-Signature header. This enables you to verify that the events were sent by GoCXL and not by any malicious actor. You can verify these signatures manually before you attempt to process the event. Before you can verify signatures, you need to retrieve your webhook's secret from your account's webhooks settings. GoCXL generates a unique secret key for each endpoint. So if you use multiple endpoints, you must obtain a secret for each one you want to verify signatures of. The Gocxl-Signature header included in each webhook event contains a timestamp and one or more signatures. The timestamp is prefixed by t=, and each signature is prefixed by a scheme. Schemes start with v, followed by an integer. Currently, the only valid live signature scheme are v1 and v2. Gocxl-Signature: t=1638280062,v1=bb276e91ad7b038d19021bfd37dd052f9f7c919b2b58bd29abbb6d97c13f0e5c

List all webhooks

To list all webhooks in your account, send a GET request to /api/v1/webhooks.

The response body will be a JSON object with a key of webhooks. This will be set to an array containing objects each representing a webhook.

Authorizations:
oauth
query Parameters
active
boolean
Example: active=true

Used to filter webhooks by its status.

events[]
Array of strings
Example: events[]=email.single.send

Used to filter webhooks by specific events.

locales[]
Array of strings
Example: locales[]=nl-NL

Used to filter webhooks by specific locales.

object

Used to order webhooks by created_at. Example: sort[created_at]=asc

cursor
string

The requested cursor token for paginated responses.

limit
integer
Default: 20

The requested amount of items for paginated responses.

Responses

Response samples

Content type
application/json
{
  • "webhooks": [
    ]
}

Retrieve an existing webhook

To show information about a webhook, send a GET request to /api/v1/webhooks/$WEBHOOK_ID.

Authorizations:
oauth
path Parameters
webhook_id
required
string <uuid>
Example: 05926e22-152d-484e-b4b7-73928d829350

A unique identifier for a webhook.

Responses

Response samples

Content type
application/json
{
  • "webhook": {
    }
}

List all webhook responses

To list all webhook responses for a webhook in your account, send a GET request to /api/v1/webhooks/:webhook_id/responses.

Authorizations:
oauth
path Parameters
webhook_id
required
string <uuid>
Example: 05926e22-152d-484e-b4b7-73928d829350

A unique identifier for a webhook.

query Parameters
object

Used to order webhook_responses by created_at, status and/or duration. Example: sort[created_at]=asc&sort[duration]=desc

cursor
string

The requested cursor token for paginated responses.

limit
integer
Default: 20

The requested amount of items for paginated responses.

Responses

Response samples

Content type
application/json
{
  • "webhook_responses": [
    ]
}

Create a Webhook response

Create a new webhook response by submitting the parameters required to POST /api/v1/webhooks/:webhook_id/responses.

Authorizations:
oauth
path Parameters
webhook_id
required
string <uuid>
Example: 05926e22-152d-484e-b4b7-73928d829350

A unique identifier for a webhook.

Request Body schema: application/json
required
object

The JSON payload that will be sent to the webhook and which will be used for signing the request

Responses

Request samples

Content type
application/json
{
  • "request_payload": {
    }
}

Response samples

Content type
application/json
{
  • "webhook": {
    }
}

Create a Webhook response

Create a new webhook response by submitting the parameters required to POST /api/v1/webhooks/:webhook_id/responses/:webhook_response_id.

Authorizations:
oauth
path Parameters
webhook_id
required
string <uuid>
Example: 05926e22-152d-484e-b4b7-73928d829350

A unique identifier for a webhook.

webhook_response_id
required
string <uuid>
Example: 05926e22-152d-484e-b4b7-73928d829350

A unique identifier for a webhook response.

Request Body schema: application/json
required
object

The JSON payload that will be sent to the webhook and which will be used for signing the request

Responses

Request samples

Content type
application/json
{
  • "request_payload": {
    }
}

Response samples

Content type
application/json
{
  • "webhook": {
    }
}

API::V2::Categories

List all categories

To list all categories in your account, send a GET request to /api/v2/categories.

The response body will be a JSON object with a key of categories. This will be set to an array containing objects each representing a category.

Authorizations:
oauth
query Parameters
slug
string
Example: slug=insurances

Used to filter categories by a specific slug.

locales[]
Array of strings
Example: locales[]=nl-NL

Used to filter categories by specific locales.

object

Used to order categories by created_at and/or name. Example: sort[created_at]=asc&sort[name]=desc

page
integer
Default: 1

The page number that you want to request.

per_page
integer
Default: 20

The requested amount of items for paginated responses.

object

Used to filter by account metadata. Example: metadata[key[subkey]]=value

Responses

Response samples

Content type
application/json
{
  • "categories": [
    ]
}

List all organizations of a category

To list all organizations in your account, send a GET request to /api/v2/$CATEGORY_ID/organizations.

The response body will be a JSON object with a key of organizations. This will be set to an array containing objects each representing a organization.

Authorizations:
oauth
path Parameters
category_id
required
string <uuid>
Example: dff66101-e1da-4e93-bad0-12908a8be91d

A unique identifier for a category.

query Parameters
object

Used to order organizations by created_at and/or name. Example: sort[created_at]=desc&sort[name]=asc

page
integer
Default: 1

The page number that you want to request.

per_page
integer
Default: 20

The requested amount of items for paginated responses.

object

Used to filter by account metadata. Example: metadata[key[subkey]]=value

Responses

Response samples

Content type
application/json
{
  • "organizations": [
    ]
}

API::V2::Letters

List all letters

To list all letters in your account, send a GET request to /api/v2/letters.

The response body will be a JSON object with a key of letters. This will be set to an array containing objects each representing a letter.

Authorizations:
oauth
query Parameters
object

Used to order letters by created_at. Example: sort[created_at]=asc

page
integer
Default: 1

The page number that you want to request.

per_page
integer
Default: 20

The requested amount of items for paginated responses.

object

Used to filter by account metadata. Example: metadata[key[subkey]]=value

Responses

Response samples

Content type
application/json
{
  • "letters": [
    ]
}

List all letter events

To list all letter events in your account, send a GET request to /api/v2/letters/$LETTER_ID/events.

The response body will be a JSON object with a key of events. This will be set to an array containing objects each representing a letter event.

Authorizations:
oauth
path Parameters
letter_id
required
string <uuid>
Example: 87ed0487-7e18-4380-9028-3d7fd2c46433

A unique identifier for a letter.

query Parameters
object

Used to order letter_events by received_at. Example: sort[received_at]=asc

page
integer
Default: 1

The page number that you want to request.

per_page
integer
Default: 20

The requested amount of items for paginated responses.

Responses

Response samples

Content type
application/json
{
  • "letter_events": [
    ]
}

API::V2::Organizations

List all organizations

To list all organizations in your account, send a GET request to /api/v2/organizations.

The response body will be a JSON object with a key of organizations. This will be set to an array containing objects each representing a organization.

Authorizations:
oauth
query Parameters
slug
string
Example: slug=allianz-nederland

Used to filter organizations by a specific slug.

category
string
Example: category=insurances

Used to filter organizations by a specific category.

locales[]
Array of strings
Example: locales[]=nl-NL

Used to filter organizations by specific locales.

url
string
Example: url=allianz.nl

Used to filter organizations by a (partial) URL.

object

Used to order organizations by created_at and/or name. Example: sort[created_at]=desc&sort[name]=asc

page
integer
Default: 1

The page number that you want to request.

per_page
integer
Default: 20

The requested amount of items for paginated responses.

object

Used to filter by account metadata. Example: metadata[key[subkey]]=value

Responses

Response samples

Content type
application/json
{
  • "organizations": [
    ]
}

List all organizations/products based on the given parameters

To list all organizations/products in your account, send a POST request to /api/v2/cancellations_selection.

Authorizations:
oauth
query Parameters
account_ids
required
Array of strings <uuid>
Example: account_ids=0df21c85-54f5-4ce9-be17-4a2fb63e958c&account_ids=12321c85-54f5-4ce9-be17-4a2fb63e958c

Filter organizations/products by account ids.

organization_id
string <uuid>
Example: organization_id=0df21c85-54f5-4ce9-be17-4a2fb63e958c

If specified will return the products of this organization.

category_ids
Array of strings <uuid>
Example: category_ids=0df21c85-54f5-4ce9-be17-4a2fb63e958c&category_ids=12321c85-54f5-4ce9-be17-4a2fb63e958c

Filter organizations/products by a specific categories.

locale_codes
Array of strings
Example: locale_codes=en-nl&locale_codes=es-es

Filter organizations/products by locales.

limit
integer [ 1 .. 50 ]
Example: limit=10

Limit the number of organizations/products returned.

date_from
string <date>
Example: date_from=2020-01-01

Filter organizations/products by a specific date.

date_to
string <date>
Example: date_to=2020-01-01

Filter organizations/products by a specific date.

predefined_period
string
Example: predefined_period=today

Filter organizations/products by a predefined period. Possible options are 'today', 'this_week' or 'this_month'.

order_by
string
Example: order_by=name

Order organizations/products by a specific field. Possible options are 'most_cancelled' or 'recent'.

Responses

Response samples

Content type
application/json
{
  • "organizations": [
    ]
}

List all products of an organization.

To list all products for an organizations in your account, send a GET request to /api/v2/organizations/$ORGANIZATION_ID/products.

The response body will be a JSON object with a key of products. This will be set to an array containing objects each representing a product.

Authorizations:
oauth
path Parameters
organization_id
required
string <uuid>
Example: 0df21c85-54f5-4ce9-be17-4a2fb63e958c

A unique identifier for an organization.

query Parameters
slug
string
Example: slug=liability-insurance

Used to filter products by a specific slug.

locales[]
Array of strings
Example: locales[]=nl-NL

Used to filter products by specific locales.

url
string
Example: url=allianz.nl

Used to filter products by a (partial) URL.

object

Used to order products by created_at and/or name. Example: sort[created_at]=desc&sort[name]=asc

page
integer
Default: 1

The page number that you want to request.

per_page
integer
Default: 20

The requested amount of items for paginated responses.

object

Used to filter by account metadata. Example: metadata[key[subkey]]=value

Responses

Response samples

Content type
application/json
{
  • "products": [
    ]
}

Search for organizations or products

To find Organizations or Products matching the search string, send a GET request to /api/v2/search.

Authorizations:
oauth
query Parameters
q
string

The input that needs to be searched for

record_type
string
Example: record_type=product

Used to filter results by their type. Possible options are 'organization' or 'product'.

locale
string
Example: locale=nl-NL

Used to filter results by their locale.

page
integer
Default: 1

The page number that you want to request.

per_page
integer
Default: 20

The requested amount of items for paginated responses.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

API::V2::Products

Search for organizations or products

To find Organizations or Products matching the search string, send a GET request to /api/v2/search.

Authorizations:
oauth
query Parameters
q
string

The input that needs to be searched for

record_type
string
Example: record_type=product

Used to filter results by their type. Possible options are 'organization' or 'product'.

locale
string
Example: locale=nl-NL

Used to filter results by their locale.

page
integer
Default: 1

The page number that you want to request.

per_page
integer
Default: 20

The requested amount of items for paginated responses.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

API::V2::Providers

List all providers

To list all providers in your account, send a GET request to /api/v2/providers.

The response body will be a JSON object with a key of providers. This will be set to an array containing objects each representing a provider.

Authorizations:
oauth
query Parameters
object

Used to order providers by created_at, name, provider_type and/or type. Example: sort[created_at]=desc&sort[name]=asc

page
integer
Default: 1

The page number that you want to request.

per_page
integer
Default: 20

The requested amount of items for paginated responses.

Responses

Response samples

Content type
application/json
{
  • "providers": [
    ]
}

API::V2::Searches

Search for organizations or products

To find Organizations or Products matching the search string, send a GET request to /api/v2/search.

Authorizations:
oauth
query Parameters
q
string

The input that needs to be searched for

record_type
string
Example: record_type=product

Used to filter results by their type. Possible options are 'organization' or 'product'.

locale
string
Example: locale=nl-NL

Used to filter results by their locale.

page
integer
Default: 1

The page number that you want to request.

per_page
integer
Default: 20

The requested amount of items for paginated responses.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

API::V2::Webhooks

List all webhooks

To list all webhooks in your account, send a GET request to /api/v2/webhooks.

The response body will be a JSON object with a key of webhooks. This will be set to an array containing objects each representing a webhook.

Authorizations:
oauth
query Parameters
active
boolean
Example: active=true

Used to filter webhooks by its status.

events[]
Array of strings
Example: events[]=email.single.send

Used to filter webhooks by specific events.

locales[]
Array of strings
Example: locales[]=nl-NL

Used to filter webhooks by specific locales.

object

Used to order webhooks by created_at. Example: sort[created_at]=asc

page
integer
Default: 1

The page number that you want to request.

per_page
integer
Default: 20

The requested amount of items for paginated responses.

Responses

Response samples

Content type
application/json
{
  • "webhooks": [
    ]
}

List all webhook responses

To list all webhook responses for a webhook in your account, send a GET request to /api/v2/webhooks/:webhook_id/responses.

Authorizations:
oauth
path Parameters
webhook_id
required
string <uuid>
Example: 05926e22-152d-484e-b4b7-73928d829350

A unique identifier for a webhook.

query Parameters
object

Used to order webhook_responses by created_at, status and/or duration. Example: sort[created_at]=asc&sort[duration]=desc

page
integer
Default: 1

The page number that you want to request.

per_page
integer
Default: 20

The requested amount of items for paginated responses.

Responses

Response samples

Content type
application/json
{
  • "webhook_responses": [
    ]
}

Widget::Letters

Create a new letter

Create a new letter by submitting the parameters required by the template to POST /api/widget/$WIDGET_TOKEN/letters.

Authorizations:
oauth
path Parameters
widget_token
required
string <uuid>
Example: 459a5993-1560-44bd-b879-258075b77e13

The requested token for Widget authorization access.

header Parameters
Origin
required
string <<scheme>://<hostname>(:<port>)>
Example: http://example.com

Indicates the origin (schema, hostname, and port) that caused the request

Request Body schema: application/json
organization_id
required
string <uuid>

A string specifying the UUID of the organization the letter is intended for.

product_id
string <uuid>

An optional string specifying the UUID of the product the letter is intended for.

provider_id
string <uuid>

A string specifying the UUID of the provider to use when sending the letter.

locale
required
string

The locale of the letter.

signature_type
string

The type of signature (could be text or image)

signature_data
string

The data for the signature. Will be the name for signature_type text and the base64 encode string for signature_type image

required
object

The parameters to use when generating the letter as described by the fields of the organization's or product's letter template.

consent
boolean or null

A boolean indicating if the user gave explicit consent to create the letter request. Only required when either the organization or products requires so.

proof_of_ids
Array of strings

An array of ID documents as base64 encoded blobs.

metadata
object

An optional set of key-value pairs that are attached for your account. Please note that:

  • Keys can only contain a-z (lowercase), - and _ with a max length of 255
  • Each value for a key can not be more than 100Kb

Responses

Request samples

Content type
application/json
{
  • "organization_id": "20ab8e7e-8d51-4144-b92a-03af909a6895",
  • "product_id": "bfc501cf-dc45-40ca-aba3-b05018c8f8be",
  • "provider_id": "20ab8e7e-8d51-4144-b92a-03af909a6895",
  • "locale": "nl-NL",
  • "signature_type": "text",
  • "signature_data": "John Doe",
  • "parameters": {
    },
  • "consent": true,
  • "proof_of_ids": [
    ],
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "letter": {
    }
}

Retrieve an existing letter

To show information about a letter, send a GET request to /api/widget/$WIDGET_TOKEN/letters/$LETTER_ID.

Authorizations:
oauth
path Parameters
letter_id
required
string <uuid>
Example: 87ed0487-7e18-4380-9028-3d7fd2c46433

A unique identifier for a letter.

widget_token
required
string <uuid>
Example: 459a5993-1560-44bd-b879-258075b77e13

The requested token for Widget authorization access.

Responses

Response samples

Content type
application/json
{
  • "letter": {
    }
}

Retrieve document for an existing letters

To download the generated document for a letter, send a GET request to /api/widget/$WIDGET_TOKEN/letters/$LETTER_ID/document.

The response body will be a binary stream containing the document.

Authorizations:
oauth
path Parameters
letter_id
required
string <uuid>
Example: 87ed0487-7e18-4380-9028-3d7fd2c46433

A unique identifier for a letter.

widget_token
required
string <uuid>
Example: 459a5993-1560-44bd-b879-258075b77e13

The requested token for Widget authorization access.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Generate a PDF document from a letter payload

To generate a document from a letter payload and download it, send a POST request with payload to /api/widget/$WIDGET_TOKEN/generate_pdf.

The response body will be a binary stream containing the document.

Authorizations:
oauth
path Parameters
widget_token
required
string <uuid>
Example: 459a5993-1560-44bd-b879-258075b77e13

The requested token for Widget authorization access.

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "letter": {
    }
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Widget::Organizations

List all organizations

To list all organizations in your account, send a GET request to /api/widget/$WIDGET_TOKEN/organizations.

The response body will be a JSON object with a key of organizations. This will be set to an array containing objects each representing a organization.

Authorizations:
oauth
path Parameters
widget_token
required
string <uuid>
Example: 459a5993-1560-44bd-b879-258075b77e13

The requested token for Widget authorization access.

query Parameters
slug
string
Example: slug=allianz-nederland

Used to filter organizations by a specific slug.

category
string
Example: category=insurances

Used to filter organizations by a specific category.

locales[]
Array of strings
Example: locales[]=nl-NL

Used to filter organizations by specific locales.

url
string
Example: url=allianz.nl

Used to filter organizations by a (partial) URL.

object

Used to order organizations by created_at and/or name. Example: sort[created_at]=desc&sort[name]=asc

page
integer
Default: 1

The page number that you want to request.

per_page
integer
Default: 20

The requested amount of items for paginated responses.

object

Used to filter by account metadata. Example: metadata[key[subkey]]=value

Responses

Response samples

Content type
application/json
{
  • "organizations": [
    ]
}

Retrieve an existing organization

To show information about an organization, send a GET request to /api/widget/$WIDGET_TOKEN/organizations/$ORGANIZATION_ID.

Authorizations:
oauth
path Parameters
organization_id
required
string <uuid>
Example: 0df21c85-54f5-4ce9-be17-4a2fb63e958c

A unique identifier for an organization.

widget_token
required
string <uuid>
Example: 459a5993-1560-44bd-b879-258075b77e13

The requested token for Widget authorization access.

Responses

Response samples

Content type
application/json
{
  • "organization": {
    }
}

List all products of an organization.

To list all products for an organizations in your account, send a GET request to /api/widget/$WIDGET_TOKEN/organizations/$ORGANIZATION_ID/products.

The response body will be a JSON object with a key of products. This will be set to an array containing objects each representing a product.

Authorizations:
oauth
path Parameters
organization_id
required
string <uuid>
Example: 0df21c85-54f5-4ce9-be17-4a2fb63e958c

A unique identifier for an organization.

widget_token
required
string <uuid>
Example: 459a5993-1560-44bd-b879-258075b77e13

The requested token for Widget authorization access.

query Parameters
slug
string
Example: slug=liability-insurance

Used to filter products by a specific slug.

locales[]
Array of strings
Example: locales[]=nl-NL

Used to filter products by specific locales.

url
string
Example: url=allianz.nl

Used to filter products by a (partial) URL.

object

Used to order products by created_at and/or name. Example: sort[created_at]=desc&sort[name]=asc

page
integer
Default: 1

The page number that you want to request.

per_page
integer
Default: 20

The requested amount of items for paginated responses.

object

Used to filter by account metadata. Example: metadata[key[subkey]]=value

Responses

Response samples

Content type
application/json
{
  • "products": [
    ]
}

Search for organizations or products

To find Organizations or Products matching the search string, send a GET request to /api/widget/$WIDGET_TOKEN/search.

Authorizations:
oauth
path Parameters
widget_token
required
string <uuid>
Example: 459a5993-1560-44bd-b879-258075b77e13

The requested token for Widget authorization access.

query Parameters
q
string

The input that needs to be searched for

record_type
string
Example: record_type=product

Used to filter results by their type. Possible options are 'organization' or 'product'.

locale
required
string
Example: locale=nl-NL

Used to filter results by their locale.

page
integer
Default: 1

The page number that you want to request.

per_page
integer
Default: 20

The requested amount of items for paginated responses.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Widget::Products

Retrieve an generic product for an organization

To show information about an organization's generic product, send a GET request to /api/widget/$WIDGET_TOKEN/organizations/$ORGANIZATION_ID/products/generic.

Authorizations:
oauth
path Parameters
organization_id
required
string <uuid>
Example: 0df21c85-54f5-4ce9-be17-4a2fb63e958c

A unique identifier for an organization.

widget_token
required
string <uuid>
Example: 459a5993-1560-44bd-b879-258075b77e13

The requested token for Widget authorization access.

Responses

Response samples

Content type
application/json
{
  • "product": {
    }
}

Search for organizations or products

To find Organizations or Products matching the search string, send a GET request to /api/widget/$WIDGET_TOKEN/search.

Authorizations:
oauth
path Parameters
widget_token
required
string <uuid>
Example: 459a5993-1560-44bd-b879-258075b77e13

The requested token for Widget authorization access.

query Parameters
q
string

The input that needs to be searched for

record_type
string
Example: record_type=product

Used to filter results by their type. Possible options are 'organization' or 'product'.

locale
required
string
Example: locale=nl-NL

Used to filter results by their locale.

page
integer
Default: 1

The page number that you want to request.

per_page
integer
Default: 20

The requested amount of items for paginated responses.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Widget::WidgetSettings

Retrieve an existing widget setting

To show information about a widget setting, send a GET request to /api/widget/$WIDGET_TOKEN/settings.

Authorizations:
oauth
path Parameters
widget_token
required
string <uuid>
Example: 459a5993-1560-44bd-b879-258075b77e13

The requested token for Widget authorization access.

Responses

Response samples

Content type
application/json
{
  • "widget_setting": {
    }
}

Widget::Searches

Search for organizations or products

To find Organizations or Products matching the search string, send a GET request to /api/widget/$WIDGET_TOKEN/search.

Authorizations:
oauth
path Parameters
widget_token
required
string <uuid>
Example: 459a5993-1560-44bd-b879-258075b77e13

The requested token for Widget authorization access.

query Parameters
q
string

The input that needs to be searched for

record_type
string
Example: record_type=product

Used to filter results by their type. Possible options are 'organization' or 'product'.

locale
required
string
Example: locale=nl-NL

Used to filter results by their locale.

page
integer
Default: 1

The page number that you want to request.

per_page
integer
Default: 20

The requested amount of items for paginated responses.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}