logo
API docs by Redocly

Dintero API (LATEST)

Download OpenAPI specification:Download

API Integration Support: integration@dintero.com License: UNLICENSED

API for managing Receipts, Discounts, Customers, Wallets and Webhooks

Introduction

The Dintero API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors.

To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no "switch" for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test mode incur no cost.

Downloads

Download the OpenAPI specification

  • customers : API for managing customers

  • discounts : API for managing discount for customers

  • products : API for managing products

  • hooks : API for managing webhooks

  • receipts : API for managing receipts

  • wallets : API for managing virtuall cards, digital gift cards and transactions

authenticate

Authorize Passwordless link

This endpoint is used to authorize Passwordless link sent to user by email/sms.

A valid request will redirect to This is the OAuth 2.0 grant that Client-side web apps utilize in order to access an API.

Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

query Parameters
audience
required
string

The unique identifier of the target API you want to access.

response_type
required
string
Value: "authenticate"

This will specify the type of token you will receive at the end of the flow. Use token to get only an access_token

If response_type=token, after the user authenticates with the provider, this will redirect them to your application callback URL while passing the access_token in the address location.hash. This is used for Single Page Apps and on Native Mobile SDKs.

client_id
required
string

Your application's Client ID.

verification_code
required
string

one-time verification-code

scope
string
Value: "openid"

The scopes which you want to request authorization for.

state
string

An opaque value the clients adds to the initial request that Dintero includes when redirecting the back to the client. This value must be used by the client to prevent CSRF attacks.

redirect_uri
string

The URL to which Dintero will redirect the browser after authorization has been granted by the user.

The redirect_uri value must be specified as a valid callback URL under your Client's Settings.

connection
string

The name of the connection configured to your client.

Responses

Response samples

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

Authorize with OIDC

path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

query Parameters
audience
required
string

The unique identifier of the target API you want to access. The audience must have a Grant with OIDC configured

response_type
required
string
Value: "code"
client_id
required
string

The client_id of your application

redirect_uri
required
string

The URL to redirect after authorization has been granted by the user.

scope
string

Scope of the access request, space-separated list.

client_token
string
Example: client_token=eyJhbGci...t7P4

Authorization token to use if no authorization header is included

Responses

Response samples

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

Token verified by OIDC

Use this endpoint to obtains an access token by presenting its authorization grant

scopes:

  • write:accounts:/auth/users
scopes: ["write:accounts:/auth/users"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
audience
required
string

The unique identifier of the target API you want to access. The audience must be a grant associated with the client that has oidc configured

code
required
string
grant_type
required
string
Value: "authorization_code"
client_id
required
string
redirect_uri
string

The redirect URL which the user agent is redirected to after finishing a login.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGci...t7P4",
  • "token_type": "Bearer",
  • "expires_in": 86400,
  • "user_info": {}
}

Passwordless

Passwordless connections do not require the user to remember a password. Instead, another mechanism is used to prove identity, such as a one-time code sent through email or SMS, every time the account user logs in.

  • The client_id/audience must have a grant with type authorization_code to allow sending verification-code
  • This endpoint is designed to be called from the client-side and is subjected to rate limits

scopes:

  • admin:accounts
  • write:accounts
  • write:accounts:/auth/passwordless
  • write:accounts:/auth/passwordless-sms
  • write:accounts:/auth/passwordless-email
scopes: ["admin:accounts","write:accounts","write:accounts:/auth/passwordless","write:accounts:/auth/passwordless-sms","write:accounts:/auth/passwordless-email"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
client_id
required
string
connection
required
string
Enum: "email" "sms"

How to send the code to the user.

audience
required
string

The unique identifier of the target API you want to access.

email
string

The user's email address

type
string
Default: "customer"
Enum: "company" "customer"

Passwordless for type company/customer requires that the email is registered to a customers users

send
string
Default: "code"
Value: "code"

Use code to send a verification code.

login_session_id
string

Use login_session_id to resend the same verifcation code to an alternative connection.

Responses

Request samples

Content type
application/json
{
  • "audience": "string",
  • "client_id": "string",
  • "connection": "email",
  • "email": "string",
  • "type": "company",
  • "send": "code",
  • "login_session_id": "string"
}

Response samples

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

Passwordless Code

Passwordless connections do not require the user to remember a password. Instead, another mechanism is used to prove identity, such as a one-time code sent through email or SMS, every time the account user logs in.

Use this endpoint to generate a one-time verification-code that can be sent to the user.

The client_id/audience must have a grant with type authorization_code to allow creating a verification-code

scopes:

  • admin:accounts
  • write:accounts
  • write:accounts:/auth/passwordless/code
scopes: ["admin:accounts","write:accounts","write:accounts:/auth/passwordless/code"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
audience
required
string

The unique identifier of the target API you want to grant the user

client_id
required
string

The client whoose grants will be granted to the user, the

user_id
required
string

The user_id / subject to grant access

Responses

Request samples

Content type
application/json
{
  • "audience": "string",
  • "client_id": "string",
  • "user_id": "string"
}

Response samples

Content type
application/json
{
  • "verification_code": "string"
}

Redirect with ID token

Use this endpoint to redirect to an URL with a ID token added.

Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
redirect_uri
required
string <uri> ^https?://.*

The HTTP URL to redirect to

object <= 5 properties

Include custom claims to the ID token. Custom claims will be prefixed by ext_.

claims
Array of strings
Items Enum: "name" "email"

Specify optional claims to include in the ID token

Responses

Request samples

Content type
application/json
{
  • "redirect_uri": "http://example.com",
  • "custom_claims": {
    },
  • "claims": [
    ]
}

Response samples

Content type
application/json
{}

Revoke Token

Use this endpoint to invalidate a Refresh Token if it has been compromised.

scopes:

  • admin:accounts
  • write:accounts
  • create:accounts:auth:refresh_token
scopes: ["admin:accounts","write:accounts","create:accounts:auth:refresh_token"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
token
required
string

Responses

Request samples

Content type
application/json
{
  • "token": "YOUR_REFRESH_TOKEN"
}

Response samples

Content type
application/json
{ }

Get Token

Use this endpoint to directly request an access_token

Client Access Token

Use HTTP Basic authentication scheme for authenticating grant_type client_credentials, use client_id/client_secret as user/password.

Code/Password Token

Use HTTP Bearer authentication scheme for authenticating grant_type authorization_code or password, where the Bearer value must be a JWT toke with access to the token endpoint.

Account User Token

Use HTTP Bearer authentication scheme for authenticating grant_type account_user_token, where the Bearer value must be a account user JWT token.

Use ID token as Bearer toke if the user was authenticated externally. The ID must include a email claim that identifies the account user.

Refresh Token

Use HTTP Bearer authentication scheme for authenticating grant_type refresh_token where the Bearer value must be an Access Token for the clients that was used to create the Refresh Token.

Multi-factor authentication (MFA)

When a request is made to the endpoint to get an access token, normally you either get an error, or you get an access token. However, when the MFA is enabled, the endpoint may return a new error with error.code: mfa_required.

When an mfa_required error is returned, the client must perform a challenge. This is done by sending a request to the auth/mfa/challenge endpoint

To verify MFA using an OOB challenge, the client must make a request to this endpoint with grant_type=mfa-oob. Include the oob_code you received from the challenge response, as well as the mfa_token you received as part of mfa_required error.

scopes:

  • admin:accounts
  • write:accounts
  • write:accounts:/auth/users
  • write:accounts:/auth/users/no-mfa
scopes: ["admin:accounts","write:accounts","write:accounts:/auth/users","write:accounts:/auth/users/no-mfa"]
Authorizations:
clientAuthJWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
grant_type
required
string

Responses

Request samples

Content type
application/json
Example
{
  • "grant_type": "account_user"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGci...t7P4",
  • "token_type": "Bearer",
  • "expires_in": 86400,
  • "refresh_token": "string"
}

Exchange Token

Use this endpoint to exchange access_token to a sub-account

scopes:

  • admin:accounts
  • read:accounts
scopes: ["admin:accounts","read:accounts"]
Authorizations:
JWT
path Parameters
partner_id
required
string <^[PT]{1}\d{3}00000$> = 9 characters

An id that uniquely identifies the partner account

Request Body schema: application/json
required
account_id
required
string <^[PT]{1}\d{8}$>

The account_id to create exchange access_token for

Responses

Request samples

Content type
application/json
{
  • "account_id": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGci...t7P4",
  • "token_type": "Bearer",
  • "expires_in": 86400,
  • "refresh_token": "string"
}

clients

Clients collection

Retrieve a list of all client applications

scopes:

  • admin:accounts
  • read:accounts
scopes: ["admin:accounts","read:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Client

Creates a new client application.

scopes:

  • admin:accounts
  • write:accounts
scopes: ["admin:accounts","write:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
name
string
description
string
client_id
string

Your client ID.

callbacks
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "client_id": "string",
  • "callbacks": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "description": "string",
  • "client_id": "string",
  • "callbacks": [
    ],
  • "client_secret": "JYCRP/x7iBGWA1fun0J9laH5sEg5cP9g/4QivhfGzm4"
}

Get Client

Retrieves a client by its id.

scopes:

  • admin:accounts
  • read:accounts
scopes: ["admin:accounts","read:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

id
required
string

The id of the client

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "description": "string",
  • "client_id": "string",
  • "callbacks": [
    ]
}

Delete Client

Deletes a client and all its related assets

scopes:

  • admin:accounts
  • write:accounts
scopes: ["admin:accounts","write:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

id
required
string

The id of the client

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "description": "string",
  • "client_id": "string",
  • "callbacks": [
    ]
}

Rotate a client secret.

Rotate a client secret.

scopes:

  • admin:accounts
  • write:accounts
scopes: ["admin:accounts","write:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

id
required
string

The id of the client

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "description": "string",
  • "client_id": "string",
  • "callbacks": [
    ],
  • "client_secret": "JYCRP/x7iBGWA1fun0J9laH5sEg5cP9g/4QivhfGzm4"
}

grants

Client grants collection

Manage your Client Grants (also called Client Credentials Grants). Using Client Grants, your Client can request an access token using its credentials (a Client ID and a Client Secret). The access token then represents your Client during API calls.

Use the Grant type to limit how the grant can be used when requesting an access token. A Grant with type password can only be used when requesting an access token with grant_type set to password.

scopes:

  • admin:accounts
  • read:accounts
scopes: ["admin:accounts","read:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

query Parameters
audience
string <= 1

filter client grants by audience

client_id
string <= 1

filter client grants by client_id

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create client grant

scopes:

  • admin:accounts
  • write:accounts
scopes: ["admin:accounts","write:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
client_id
required
string
audience
required
string
scope
required
Array of strings[ items non-empty ]
type
string
Default: "any"
Enum: "any" "authorization_code" "client_credentials" "password"

Limit the usage of the grant. A grant with grant_types set to only authorization_code cannot be used in Get Token when calling the endpoint with grant_type=client_credentials

object

Open ID connect configuration for the Grant. The option enables client to verify the identify of the End-User based on the authentication performed by an authorization server

The grant type must be set to authorization_code when configured.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "client_id": "string",
  • "audience": "https://api.dintero.com/v1/accounts/P00000000",
  • "scope": [
    ],
  • "type": "any",
  • "oidc": {}
}

Delete client grant

scopes:

  • admin:accounts
  • write:accounts
scopes: ["admin:accounts","write:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

id
required
string

The id of the client grant to delete

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "client_id": "string",
  • "audience": "https://api.dintero.com/v1/accounts/P00000000",
  • "scope": [
    ],
  • "type": "any",
  • "oidc": {}
}

roles

Roles collection

Retrieve filtered list of roles that can be assigned to users.

scopes:

  • admin:accounts
  • read:accounts
scopes: ["admin:accounts","read:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

query Parameters
search
string

lookup roles matching id, name and description

name
string

lookup roles by name

include_deleted
boolean
Default: false

include deleted roles in the response

limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, end the result contains paging_token=pt1, your subsequent call can include starting_after=pt1 in order to fetch the next page of the list.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a role

scopes:

  • admin:accounts
  • write:accounts
scopes: ["admin:accounts","write:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
scope
required
Array of strings[ items non-empty ]
name
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "order support",
  • "description": "Administrate orders",
  • "scope": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "order support",
  • "description": "Administrate orders",
  • "scope": [
    ]
}

Get role

scopes:

  • admin:accounts
  • read:accounts
scopes: ["admin:accounts","read:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

role_id
required
string

The id of the rule to delete

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "order support",
  • "description": "Administrate orders",
  • "scope": [
    ]
}

Update role

scopes:

  • admin:accounts
  • write:accounts
scopes: ["admin:accounts","write:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

role_id
required
string

The id of the rule to delete

Request Body schema: application/json
required
scope
required
Array of strings[ items non-empty ]
name
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "order support",
  • "description": "Administrate orders",
  • "scope": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "order support",
  • "description": "Administrate orders",
  • "scope": [
    ]
}

Delete role

scopes:

  • admin:accounts
  • write:accounts
scopes: ["admin:accounts","write:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

role_id
required
string

The id of the rule to delete

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "order support",
  • "description": "Administrate orders",
  • "scope": [
    ]
}

keys

Get public keys

Retrieve the JSON Web Key Set (JWKS) that can be used to validate access_token

scopes:

  • admin:accounts
  • read:accounts
scopes: ["admin:accounts","read:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

users

Admin users

Create User

Create a new user

scopes:

  • admin:accounts
  • write:accounts
  • write:accounts:/auth/users
scopes: ["admin:accounts","write:accounts","write:accounts:/auth/users"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required
username
required
string [ 1 .. 255 ] characters

The user's username.

password
required
string >= 8 characters

The user's password

Array of objects (AuthUserLinks)

Links to resources related to the user, links is required when MFA is enabled.

object (AuthUserMfa)

Require Multi-factor authentication (MFA) for the user

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "links": [],
  • "mfa": {
    },
  • "password": "stringst"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "links": [],
  • "mfa": {
    }
}

Update user

Update existing user with new password

scopes:

  • admin:accounts
  • write:accounts
  • write:accounts:/auth/users
scopes: ["admin:accounts","write:accounts","write:accounts:/auth/users"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

username
required
string <= 255 characters

Username identifying the user

Request Body schema: application/json
required
password
required
string >= 8 characters

The user's password

Array of objects (AuthUserLinks)

Links to resources related to the user, links is required when MFA is enabled.

object (AuthUserMfa)

Require Multi-factor authentication (MFA) for the user

Responses

Request samples

Content type
application/json
{
  • "password": "stringst",
  • "links": [],
  • "mfa": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "links": [],
  • "mfa": {
    }
}

Delete user

Delete existing user

scopes:

  • admin:accounts
  • write:accounts
  • write:accounts:/auth/users
scopes: ["admin:accounts","write:accounts","write:accounts:/auth/users"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

username
required
string <= 255 characters

Username identifying the user

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "links": [],
  • "mfa": {
    }
}

Change username

Update existing users username

scopes:

  • admin:accounts
scopes: ["admin:accounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

username
required
string <= 255 characters

Username identifying the user

Request Body schema: application/json
required
username
required
string [ 1 .. 255 ] characters

The user's new usernname

Responses

Request samples

Content type
application/json
{
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "links": [],
  • "mfa": {
    }
}

challenge

Challenge request

Request a challenge for multi-factor authentication (MFA) based on the challenge types supported by the user.

The challenge_type is how the user will get the challenge and prove possession. Supported challenge types include:

  • oob: for SMS messages or out-of-band (OOB)

Use the response to request access token from the auth/token endpoint with grant_type=mfa_oob

scopes:

  • admin:accounts
  • write:accounts
  • write:accounts:/auth/mfa
scopes: ["admin:accounts","write:accounts","write:accounts:/auth/mfa"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required
challenge_type
required
string
Value: "oob"

The challenge type accepted by your application

mfa_token
required
string

The token received from mfa_required error.

oob_channel
string
Default: "sms"
Enum: "sms" "email"

The channel to use for OOB. Can only be provided when challenge_type is oob.

Responses

Request samples

Content type
application/json
{
  • "challenge_type": "oob",
  • "oob_channel": "sms",
  • "mfa_token": "string"
}

Response samples

Content type
application/json
{
  • "challenge_type": "oob",
  • "binding_method": "prompt",
  • "oob_code": "bkaiew...akas"
}

Recovery

Request a recovery for user with multi-factor authentication (MFA) enabled.

A recovery is done with two out-of-band (OOB) challenges over different channels.

Use the response to request access token from the auth/token endpoint with grant_type=mfa_oob.

A 403 status with mfa_required error will be returned on success, use the response to request a new challenge from the auth/mfa/challenge endpoint.

scopes:

  • admin:accounts
  • write:accounts
  • write:accounts:/auth/mfa
scopes: ["admin:accounts","write:accounts","write:accounts:/auth/mfa"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required
challenge_type
required
string
Value: "oob"

The challenge type accepted by your application

username
required
string

The end user's identifier.

audience
required
string

The unique identifier of the target API you want to access. The audience must be a grant associated with the client used in the request

oob_channel
string
Default: "sms"
Enum: "sms" "email"

The channel to use for OOB. Can only be provided when challenge_type is oob.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "challenge_type": "oob",
  • "binding_method": "prompt",
  • "oob_code": "bkaiew...akas",
  • "mfa_token": "string"
}

users

A user, aka customer, member.

Create new Customer

Create a new customer, customer_id, email and phone_number must be unique if specified. scopes:

  • admin:customers
  • write:customers
  • create:customers:/users
scopes: ["admin:customers","write:customers","create:customers:/users"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

customer to create

type
required
string
Default: "customer"
Enum: "customer" "company" "contact" "employee" "other"

Describe type of a user.

  • company property is required when using the type company
  • company property is only supported for users with type other or company
  • Creating or updating user with type employee or other requires admin:customers or write:customers scope.
  • User login is only available for users with type customer or company
metadata
object <= 40 properties

A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format. You can unset an individual key by setting its value to null and then saving. To clear all keys, set metadata to null

first_name
string or null
last_name
string or null
email
string or null

customer email, case insensitive duplication control prevents multiple user with same type to have equal email

customer@example.com is equal to CUStOMer@EXAMPLE.com

phone_number
string or null <^\+?[1-9]\d{1,14}$>

A phone number in E.164 number formatting.

attributes
object

Custom attributes

status
string or null

Status of the customer

favorite_store
string or null

customer favorite store

object

The source that recruited the customer

object

Customers consent for marketing in different channels

Array of objects (CustomerAddress)
object (CustomerTerm)
object

Company details, supported when type is Company

gender
string or null
date_of_birth
string or null <date>
Array of objects

The users that it is a contact for, supported when type is contact

customer_id
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces) An auto-generated customer_id will be created if no customer_id is provided.

password
string [ 8 .. 255 ] characters

The customer password. The caller must have scope write:accounts:/auth/users when password is included in the body

pin
string = 6 characters ^\d{6}$

6 digit customer pin, can only used for MFA login. The caller must have scope write:accounts:/auth/users when pin is included in the body

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "customer@example.com",
  • "phone_number": "+4799999999",
  • "attributes": { },
  • "status": "string",
  • "favorite_store": "string",
  • "enrolled_by": {},
  • "marketing_consent": {
    },
  • "type": "customer",
  • "addresses": [
    ],
  • "term": {
    },
  • "company": {
    },
  • "gender": "male",
  • "date_of_birth": "1990-09-20",
  • "contact_for": [
    ],
  • "customer_id": "string",
  • "password": "stringst",
  • "pin": "string"
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "customer@example.com",
  • "phone_number": "+4799999999",
  • "attributes": { },
  • "status": "string",
  • "favorite_store": "string",
  • "enrolled_by": {},
  • "marketing_consent": {
    },
  • "type": "customer",
  • "addresses": [
    ],
  • "term": {
    },
  • "company": {
    },
  • "gender": "male",
  • "date_of_birth": "1990-09-20",
  • "contact_for": [
    ],
  • "customer_id": "string"
}

User exist

Check if there is users that match the parameters. The result will match all parameters with AND. This endpoint must be enabled from PUT /customers/settings scopes:

  • admin:customers
  • read:customers
  • public:customers
scopes: ["admin:customers","read:customers","public:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
email
string

lookup customer by email

phone_number
string

lookup customer by phone_number

Responses

Response samples

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

Customer collection

Get all customers, limited by parameters. The result will match all parameters with AND. Search is done by prefix match, and + in phone_number/email must be URL encoded, (+4799999999 => %2B4799999999)

Users with type contact are by default excluded from the result, use type=contact or type=any to include contact users

The response from a request that match contact users will include the users that are linked from the contact

scopes:

  • admin:customers
  • read:customers
scopes: ["admin:customers","read:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
token_value
string

lookup customers by token value

token_type
string

lookup customer by token type

email
string

lookup customer by email

phone_number
string

lookup customer by phone_number

type
string
Enum: "customer" "company" "contact" "employee" "other" "any"

lookup customer by type

search
string

lookup customer where search term match name, phone number, customer_id or email. The search term will be matched with the user details

tag_id
string

lookup customers by tag id

include_deleted
boolean
Default: false

include deleted customers in the response. A deleted user will only have an id/customer_id, created_at/created_by and deleted_at/deleted_by set All other details of a customer, like email or phone_number will be deleted.

attributes_keys
Array of strings <= 4 items

include customers that has all the attributes.

attributes_values
Array of strings <= 4 items

Combine with attributes_keys to include customers with match on attribute values

since_datetime
string <date-time>

lookup customers that has been added or modified since an ISO timestamp. NOTE: this parameter can't be combined with starting_after parameter. Retrieve next page by updating since_datetime to the latest updated_at value found in the result

limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, end the result contains paging_token=pt1, your subsequent call can include starting_after=pt1 in order to fetch the next page of the list.

total
boolean
Default: false

include total-count header in the response

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Customer details

Customer details scopes:

  • admin:customers
  • read:customers
  • user:customers
  • user:customers:/customer/details
scopes: ["admin:customers","read:customers","user:customers","user:customers:/customer/details"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "customer@example.com",
  • "phone_number": "+4799999999",
  • "attributes": { },
  • "status": "string",
  • "favorite_store": "string",
  • "enrolled_by": {},
  • "marketing_consent": {
    },
  • "type": "customer",
  • "addresses": [
    ],
  • "term": {
    },
  • "company": {
    },
  • "gender": "male",
  • "date_of_birth": "1990-09-20",
  • "contact_for": [
    ],
  • "customer_id": "string"
}

Update Customer

Update customer properties, properties not included in the body will remain unchanged. scopes:

  • admin:customers
  • write:customers
  • user:customers
scopes: ["admin:customers","write:customers","user:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

Request Body schema: application/json
required

Customer update

first_name
string or null
last_name
string or null
email
string or null

customer email, case insensitive duplication control prevents multiple user with same type to have equal email

customer@example.com is equal to CUStOMer@EXAMPLE.com

phone_number
string or null <^\+?[1-9]\d{1,14}$>

A phone number in E.164 number formatting.

attributes
object

Custom attributes

status
string or null

Status of the customer

favorite_store
string or null

customer favorite store

object

The source that recruited the customer

object

Customers consent for marketing in different channels

type
string
Default: "customer"
Enum: "customer" "company" "contact" "employee" "other"

Describe type of a user.

  • company property is required when using the type company
  • company property is only supported for users with type other or company
  • Creating or updating user with type employee or other requires admin:customers or write:customers scope.
  • User login is only available for users with type customer or company
Array of objects (CustomerAddress)
object (CustomerTerm)
object

Company details, supported when type is Company

gender
string or null
date_of_birth
string or null <date>
Array of objects

The users that it is a contact for, supported when type is contact

password
string [ 8 .. 255 ] characters

The customer password. The caller must have scope write:accounts:/auth/users when password is included in the body

pin
string = 6 characters ^\d{6}$

6 digit customer pin, can only be used for MFA login. The caller must have scope write:accounts:/auth/users when pin is included in the body

Responses

Request samples

Content type
application/json
{
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "customer@example.com",
  • "phone_number": "+4799999999",
  • "attributes": { },
  • "status": "string",
  • "favorite_store": "string",
  • "enrolled_by": {},
  • "marketing_consent": {
    },
  • "type": "customer",
  • "addresses": [
    ],
  • "term": {
    },
  • "company": {
    },
  • "gender": "male",
  • "date_of_birth": "1990-09-20",
  • "contact_for": [
    ],
  • "password": "stringst",
  • "pin": "string"
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "customer@example.com",
  • "phone_number": "+4799999999",
  • "attributes": { },
  • "status": "string",
  • "favorite_store": "string",
  • "enrolled_by": {},
  • "marketing_consent": {
    },
  • "type": "customer",
  • "addresses": [
    ],
  • "term": {
    },
  • "company": {
    },
  • "gender": "male",
  • "date_of_birth": "1990-09-20",
  • "contact_for": [
    ],
  • "customer_id": "string"
}

Delete customer

Delete single customer scopes:

  • admin:customers
  • write:customers
  • user:customers
scopes: ["admin:customers","write:customers","user:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

query Parameters
delete_tokens
boolean
Default: false

Delete all tokens owned by the customer

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "customer@example.com",
  • "phone_number": "+4799999999",
  • "attributes": { },
  • "status": "string",
  • "favorite_store": "string",
  • "enrolled_by": {},
  • "marketing_consent": {
    },
  • "type": "customer",
  • "addresses": [
    ],
  • "term": {
    },
  • "company": {
    },
  • "gender": "male",
  • "date_of_birth": "1990-09-20",
  • "contact_for": [
    ],
  • "customer_id": "string"
}

Change customer_id

Update customer_id for an customer warning: Any external resources "owned" by the user, i.e receipts, discounts etc. will not be updated with the new customer_id. A new metadata property dintero_change_customer_id_{timestamp}.{hash} will be added everytime the customer_id is changed Following data will be included in the metadata property

  • created_at
  • created_by
  • old
  • new scopes:
  • admin:customers
  • admin:accounts
scopes: ["admin:customers","admin:accounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

Request Body schema: application/json
required

Customer update

customer_id
string [ 1 .. 255 ] characters

New customer_id (must not have trailing or leading spaces).

Responses

Request samples

Content type
application/json
{
  • "customer_id": "string"
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "customer@example.com",
  • "phone_number": "+4799999999",
  • "attributes": { },
  • "status": "string",
  • "favorite_store": "string",
  • "enrolled_by": {},
  • "marketing_consent": {
    },
  • "type": "customer",
  • "addresses": [
    ],
  • "term": {
    },
  • "company": {
    },
  • "gender": "male",
  • "date_of_birth": "1990-09-20",
  • "contact_for": [
    ],
  • "customer_id": "string"
}

tokens

Get token events

Get the token events scopes:

  • admin:customers
  • read:customers
scopes: ["admin:customers","read:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, end the result contains paging_token=pt1, your subsequent call can include starting_after=pt1 in order to fetch the next page of the list.

since_datetime
string <date-time>

Only token events added/updated at or after this time is returned NOTE: this parameter can't be combined with starting_after parameter. Retrieve next page by updating since_datetime to the latest updated_at value found in the result.

deleted_since
string <date-time>

return only token events that has been deleted

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete token events

Delete the connection between token (type/value) and list of events. Include an event in the request to store the reason for the request scopes:

  • admin:customers
  • write:customers
scopes: ["admin:customers","write:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required
required
object (TokenTypeValue)

Lookup by token type and value

object

Record an delete event, the status will be set to DELETED.

Responses

Request samples

Content type
application/json
{
  • "token": {
    },
  • "event": {
    }
}

Find / Add token events

Find details about a token, inclusive details about any customer the token belongs to and any token events recorded Include event in the request to update the status of the token scopes:

  • admin:customers
  • write:customers
scopes: ["admin:customers","write:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required
required
object (TokenTypeValue)

Lookup by token type and value

object (TokenEvent)

Record event data about a token An event can be created before the customer exist and before the token has been added to the customer

Responses

Request samples

Content type
application/json
{
  • "token": {
    },
  • "event": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer": {
    },
  • "token": {
    },
  • "status": "OPT_OUT",
  • "events": [
    ]
}

Token collections

Get all tokens for a Customer scopes:

  • admin:customers
  • read:customers
  • user:customers
scopes: ["admin:customers","read:customers","user:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

query Parameters
type
string

filter tokens on type

limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, end the result contains paging_token=pt1, your subsequent call can include starting_after=pt1 in order to fetch the next page of the list.

total
boolean
Default: false

include total-count header in the response

include_deleted
boolean
Default: true

include deleted tokens in the response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new Token

Create a new customer token scopes:

  • admin:customers
  • write:customers
  • user:customers
scopes: ["admin:customers","write:customers","user:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

query Parameters
delete_token_events
boolean
Default: false

delete all token events recorded on token type/value before creating new customer token

Request Body schema: application/json
required

customer token to add

type
required
string non-empty

identifies how or who is resposible for the token value

value
required
string non-empty
token_id
string [ 1 .. 255 ] characters

The token id you have defined for the token. (must not have trailing or leading spaces). An auto-generated token_id will be created if no token_id is provided.

metadata
object

Additional metadata about the token or the entity the token was created from

Responses

Request samples

Content type
application/json
{
  • "token_id": "string",
  • "type": "sha1:email",
  • "value": "a1b79ef1a62d94ffa86b3f3d846df0ee3993af92",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "token_id": "string",
  • "type": "sha1:email",
  • "value": "a1b79ef1a62d94ffa86b3f3d846df0ee3993af92",
  • "metadata": {
    }
}

Delete customer token

Delete Token

scopes:

  • admin:customers
  • write:customers
  • user:customers
scopes: ["admin:customers","write:customers","user:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

tid
required
string <= 255 characters

The token id you have defined for the token. (must not have trailing or leading spaces)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "token_id": "string",
  • "type": "sha1:email",
  • "value": "a1b79ef1a62d94ffa86b3f3d846df0ee3993af92",
  • "metadata": {
    }
}

password

Change password

Specify the email address of the user whose password you would like to reset. If the call is successful, the user will receive an email prompting them to change their password. The caller must have scope write:accounts:/auth/users to perform a change password request. scopes:

  • write:accounts:/auth/users
scopes: ["write:accounts:/auth/users"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required
audience
required
string

The unique identifier of the target API you want to access. The audience must be a grant associated with the client used when calling this resource.

email
required
string
type
required
string
Enum: "customer" "company"

user type to login, required as users with different type can share email

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "audience": "string",
  • "type": "customer"
}

Response samples

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

Login with email/password

Login a customer user, the caller must have scope write:accounts:/auth/users. If MFA is enabled on account, use write:accounts:/auth/users/no-mfa to skip MFA. scopes:

  • write:accounts:/auth/users
  • write:accounts:/auth/users/no-mfa
scopes: ["write:accounts:/auth/users","write:accounts:/auth/users/no-mfa"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

credentials

audience
required
string

The unique identifier of the target API you want to access. The audience must be a grant associated with the client used when calling this resource.

type
required
string
Enum: "customer" "company"

user type to login, required as users with different type can share email

password
required
string [ 4 .. 255 ] characters

The customer pin or password. The caller must have scope write:accounts:/auth/users or write:accounts:/auth/users/no-mfa when password is included in the body

email
string

Required if ident_type and ident is not set

ident_type
string
Enum: "phone_number" "email"

Required if email is not set

ident
string

Email or phone_number, depending on the ident_type.

Required if email is not set.

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "ident_type": "phone_number",
  • "ident": "string",
  • "audience": "string",
  • "type": "customer",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGci...t7P4",
  • "token_type": "Bearer",
  • "expires_in": 86400,
  • "refresh_token": "string"
}

Login with MFA

Initiate a Multi-Factor Authentication for a customer user, the caller must have scope write:accounts:/auth/users to perform a login. Post the ident_type, along with the ident and secret. The server will return a challenge response specifying the challenge_type that will have to be completed to when getting an access token from the POST /v1/accounts/{oid}/auth/token endpoint. scopes:

  • write:accounts:/auth/users
scopes: ["write:accounts:/auth/users"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

credentials

audience
required
string

The unique identifier of the target API you want to access. The audience must be a grant associated with the client used when calling this resource.

ident_type
required
string
Enum: "phone_number" "email"
ident
required
string

Email or phone_number, depending on the ident_type.

type
required
string
Enum: "customer" "company"

user type to login, required as users with different type can share email

secret
required
string

The customers pin or password.

Responses

Request samples

Content type
application/json
{
  • "ident_type": "phone_number",
  • "ident": "string",
  • "audience": "string",
  • "type": "customer",
  • "secret": "string"
}

Response samples

Content type
application/json
{}

MFA recovery

Initiate a Multi-Factor Authentication recovery login for a customer user that has forgotten/lost their secret. Specify the ident_type and the ident (email or phone_number) of the user. If the call is successful, the user will get an email with an one time recovery code that has to be submitted to the mfa_recovery endpoint. When a valid one time recovery has been posted the server response with a regular MFA challenge. Once authenticated the password or pin can be changed by updating the customer. scopes:

  • write:accounts:/auth/users
scopes: ["write:accounts:/auth/users"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required
audience
required
string

The unique identifier of the target API you want to access. The audience must be a grant associated with the client used when calling this resource.

ident_type
required
string
Enum: "phone_number" "email"
ident
required
string

Email or phone_number, depending on the ident_type.

type
required
string
Enum: "customer" "company"

user type to login, required as users with different type can share email

Responses

Request samples

Content type
application/json
{
  • "ident_type": "phone_number",
  • "ident": "string",
  • "audience": "string",
  • "type": "customer"
}

Response samples

Content type
application/json
{
  • "links": [
    ],
  • "binding_method": "prompt",
  • "oob_code": "bkaiew...akas",
  • "mfa_token": "string",
  • "challenge_type": "oob"
}

communication

Customer email/phone_number Status

Get the status of customer email / phone_number communication scopes:

  • admin:customers
  • read:customers
  • user:customers
scopes: ["admin:customers","read:customers","user:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "communication": {
    }
}

Verify Customer email/phone_number

Verify customer email/phone_number field. Consist of to steps:

  • send verification code to the customer (sms or email)
  • verify the email/phone_number by posting verification code sent to customer scopes:
  • admin:customers
  • write:customers
  • user:customers
scopes: ["admin:customers","write:customers","user:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

field
required
string
Enum: "email" "phone_number"

field to verify

operation
required
string
Enum: "send-verification-code" "confirm-verification-code"

Verify operation

Request Body schema: application/json

verification code

code
string

Verification code sent to customer

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

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

tags

Tags collection

Get all customer tags (also known as groups). scopes:

  • admin:customers
  • read:customers
scopes: ["admin:customers","read:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new Tag

Create a tag scopes:

  • admin:customers
  • write:customers
scopes: ["admin:customers","write:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

customer tag add

tag
required
string

tag value

metadata
object

A set of key/value pairs that you can attach to a tag.

Responses

Request samples

Content type
application/json
{
  • "tag": "VIP",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "tag": "VIP",
  • "metadata": { }
}

Delete Tag

Delete a tag. A deleted tag is removed from customer tags scopes:

  • admin:customers
  • write:customers
scopes: ["admin:customers","write:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

tag_id
required
string <uuid>

tag id

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "tag": "VIP",
  • "metadata": { }
}

Update Customer Tags

Update Customer Tags scopes:

  • admin:customers
  • write:customers
  • user:customers
scopes: ["admin:customers","write:customers","user:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

Request Body schema: application/json
required

tag ids to set

Array
string <uuid>

list of tag ids

Responses

Request samples

Content type
application/json
[
  • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]

Response samples

Content type
application/json
[
  • {
    }
]

Tag collection

Get tags for a customer scopes:

  • admin:customers
  • read:customers
  • user:customers
scopes: ["admin:customers","read:customers","user:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

terms

Create new Terms

Create customer terms and conditions scopes:

  • admin:customers
  • write:customers
scopes: ["admin:customers","write:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

terms to create

terms
required
string

Responses

Request samples

Content type
application/json
{
  • "terms": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "terms": "string"
}

Terms collection

Get all customer terms and conditions scopes:

  • admin:customers
  • read:customers
  • public:customers
scopes: ["admin:customers","read:customers","public:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, end the result contains paging_token=pt1, your subsequent call can include starting_after=pt1 in order to fetch the next page of the list.

include_deleted
boolean
Default: false

include deleted terms in the response

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Terms details

Get single terms and conditions scopes:

  • admin:customers
  • read:customers
  • public:customers
scopes: ["admin:customers","read:customers","public:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

tid
required
string <uuid>

terms id

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "terms": "string"
}

Delete Term

Delete the customer term scopes:

  • admin:customers
  • write:customers
scopes: ["admin:customers","write:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

tid
required
string <uuid>

terms id

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "terms": "string"
}

settings

Customers settings

Get customers settings

scopes:

  • admin:customers
  • read:customers
  • public:customers
scopes: ["admin:customers","read:customers","public:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Responses

Response samples

Content type
application/json
{
  • "users": {
    },
  • "auto_tokens": {
    },
  • "tokens": {
    },
  • "attributes": [
    ]
}

Update settings

Update customers settings

scopes:

  • admin:customers
  • write:customers
scopes: ["admin:customers","write:customers"]