API docs by Redocly

Customers API (LATEST)

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

API for managing customers

Changelog

All notable changes to the API.

2024-03-01

doc: Improve description for customer enrolled_by type, add examples

2023-10-01

new: Support new customer type contact. A user contact can be linked with users and a search matching a contact will match its linked users

2023-09-01

new: Add endpoint for validating a given address and returning close matching alternatives if found.

2020-12-01

Add endpoint for getting multiple addresses for given organization number.

2021-10-01

Support multiple users sharing the same phone_number. Use the new users.phone_number_validation.allow_duplicates option to control the unique phone_number constraint on users

2021-02-01

Extend customer enrolled_by.type to allow any string value, not just url, store and custom.

Add support for removing customer terms and include_deleted when getting list of all terms.

2021-01-01

Add support for limited access to customer details with user:customers:/customer/details

Add support for logging on without MFA even if configured with MFA

2020-12-01

new Support filter users with type query parameter.

2020-11-01

new Support filter user tokens with include_deleted query parameter.

new Support filter and search on sales locations

new Extend SalesLocation with address.latitude, address.longitude, chain, mcc, gln and franchise. The account_id will be included in any SalesLocation responses.

2020-05-01

Add setting for require verification when updating user phone_number. Prevent all update of user phone_number without completing a verification via SMS.

2020-04-01

Adds proxy to enhetsregisteret.

2020-03-10

Add support for attributes_keys and attributes_values query parameters for filtering customer users

2020-02-28

Add support for enabling automatic tokens when phone numbers or emails change

2019-09-31

Extends settings with support for configuring users customer_id_format.

Extends the TokenEvent definition with `expires_at read only property.

Extends settings with support for configuring token events expiry

2019-07-31

2019-07-31

Extend user Address, add support for latitude, longitude and comment properties.

2019-07-31

Add new endpoint for deleting a tag

2019-06-31

The scope required for accessing endpoint has changed, we will continue to support the old scopes but they was removed from the documentation

2019-05-31

Make type and company property optional when updating a customer user

2019-01-31

Support new customer type employee.

2018-06-04

Adding tokens to deleted customers will now fail with BAD_REQUEST.

Duplication control of customer.email is now case insensitive. email case will be ignore on Search and login.

Add support for query parameter total on GET user/token lists. Includes a total-count header in the response when enabled..

2018-04-11

Add support for delete_token_events parameter when creating

Add support for filtering token events by since_datetime.

Delete customer and all tokens owed by the customer in one request when using delete_tokens query parameter.

Token event status. The status in response will now be set to customer.status if a customer with status is included in the response.

2018-02-15

Add minimum length for token token_id/type/value

Add endpoint for GET/DELETE token events

2018-02-02

Add type property to the customer. Support multiple customer types, add support for Company type for additional properties

Move endpoints for retrieving/updating token (events), use one endpoint for both retrieving and updating details about a token

users

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
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 an 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
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
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
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
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 an 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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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

customers settings

object

customers user configurations

object

Automatically generate tokens for these properties on the customer

object

tokens configuration

Array of objects

user attributes

Responses

Request samples

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

Response samples

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

locations

Locations collection

Get all sales locations, the starting_after have to be set to location_id scopes:

  • admin:locations
  • read:locations
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.

search
string

lookup locations where search term match name, phone_number, email, organization_number and business_name

status
Array of strings

filter locations by status

country
Array of strings

filter locations by country

phone_number
Array of strings

filter locations by phone_number

organization_number
Array of strings

filter locations by organization_number

email
Array of strings

filter locations by email

type
Array of strings

filter locations by type

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new sales location

Create a sales location scopes:

  • admin:locations
  • write:locations
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

location to create

location_id
string <= 255 characters

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

name
string

The location's trade name which is shown to its customers (receipt/signs)

timezone
string

The location's timezone (IANA Timezone)

status
string

The location's status

language_code
string

Language code of the localized company info, as defined by BCP 47 (IETF BCP 47, "Tags for Identifying Languages").

currency
string

The three-character ISO-4217 currency. https://en.wikipedia.org/wiki/ISO_4217

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

A phone number in E.164 number formatting.

chain
string
email
string
mcc
string <iso-18245> [ 4 .. 4 ]

A four-digit Merchant Category Code (MCC) for the store ISO 18245:2003

gln
string

Company Global Location Number

organization_number
string

Company identification number

business_name
string

The location's legal name

franchise
string

The location is part of a franchise.

type
string

The location type (Physical, Mobile)

website_url
string

The location's website

object

Responses

Request samples

Content type
application/json
{
  • "name": "TKP Store",
  • "timezone": "Europe/Oslo",
  • "status": "Active",
  • "language_code": "string",
  • "currency": "NOK",
  • "phone_number": "+4799999999",
  • "chain": "SuperChain",
  • "email": "saleslocation@example.com",
  • "mcc": "5814",
  • "gln": "string",
  • "organization_number": "123456789MVA",
  • "business_name": "TKP technology AS",
  • "franchise": "Subway",
  • "type": "string",
  • "website_url": "string",
  • "address": {
    }
}

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",
  • "location_id": "S01923",
  • "name": "TKP Store",
  • "timezone": "Europe/Oslo",
  • "status": "Active",
  • "language_code": "string",
  • "currency": "NOK",
  • "phone_number": "+4799999999",
  • "chain": "SuperChain",
  • "email": "saleslocation@example.com",
  • "mcc": "5814",
  • "gln": "string",
  • "organization_number": "123456789MVA",
  • "business_name": "TKP technology AS",
  • "franchise": "Subway",
  • "type": "string",
  • "website_url": "string",
  • "address": {
    }
}

Location details

Get single sales location scopes:

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

An id that uniquely identifies the account.

lid
required
string <= 255 characters

location 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",
  • "location_id": "S01923",
  • "name": "TKP Store",
  • "timezone": "Europe/Oslo",
  • "status": "Active",
  • "language_code": "string",
  • "currency": "NOK",
  • "phone_number": "+4799999999",
  • "chain": "SuperChain",
  • "email": "saleslocation@example.com",
  • "mcc": "5814",
  • "gln": "string",
  • "organization_number": "123456789MVA",
  • "business_name": "TKP technology AS",
  • "franchise": "Subway",
  • "type": "string",
  • "website_url": "string",
  • "address": {
    }
}

Update Sales location

Update location properties scopes:

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

An id that uniquely identifies the account.

lid
required
string <= 255 characters

location id

Request Body schema: application/json
required

Location update

name
string

The location's trade name which is shown to its customers (receipt/signs)

timezone
string

The location's timezone (IANA Timezone)

status
string

The location's status

language_code
string

Language code of the localized company info, as defined by BCP 47 (IETF BCP 47, "Tags for Identifying Languages").

currency
string

The three-character ISO-4217 currency. https://en.wikipedia.org/wiki/ISO_4217

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

A phone number in E.164 number formatting.

chain
string
email
string
mcc
string <iso-18245> [ 4 .. 4 ]

A four-digit Merchant Category Code (MCC) for the store ISO 18245:2003

gln
string

Company Global Location Number

organization_number
string

Company identification number

business_name
string

The location's legal name

franchise
string

The location is part of a franchise.

type
string

The location type (Physical, Mobile)

website_url
string

The location's website

object

Responses

Request samples

Content type
application/json
{
  • "name": "TKP Store",
  • "timezone": "Europe/Oslo",
  • "status": "Active",
  • "language_code": "string",
  • "currency": "NOK",
  • "phone_number": "+4799999999",
  • "chain": "SuperChain",
  • "email": "saleslocation@example.com",
  • "mcc": "5814",
  • "gln": "string",
  • "organization_number": "123456789MVA",
  • "business_name": "TKP technology AS",
  • "franchise": "Subway",
  • "type": "string",
  • "website_url": "string",
  • "address": {
    }
}

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",
  • "location_id": "S01923",
  • "name": "TKP Store",
  • "timezone": "Europe/Oslo",
  • "status": "Active",
  • "language_code": "string",
  • "currency": "NOK",
  • "phone_number": "+4799999999",
  • "chain": "SuperChain",
  • "email": "saleslocation@example.com",
  • "mcc": "5814",
  • "gln": "string",
  • "organization_number": "123456789MVA",
  • "business_name": "TKP technology AS",
  • "franchise": "Subway",
  • "type": "string",
  • "website_url": "string",
  • "address": {
    }
}

Delete location

Delete single location scopes:

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

An id that uniquely identifies the account.

lid
required
string <= 255 characters

location 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",
  • "location_id": "S01923",
  • "name": "TKP Store",
  • "timezone": "Europe/Oslo",
  • "status": "Active",
  • "language_code": "string",
  • "currency": "NOK",
  • "phone_number": "+4799999999",
  • "chain": "SuperChain",
  • "email": "saleslocation@example.com",
  • "mcc": "5814",
  • "gln": "string",
  • "organization_number": "123456789MVA",
  • "business_name": "TKP technology AS",
  • "franchise": "Subway",
  • "type": "string",
  • "website_url": "string",
  • "address": {
    }
}

organizations

Get addresses for organization number from external organization registry

scopes:

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

An id that uniquely identifies the account.

country
required
string

ISO 3166-1 country code

organization_number
required
string

Organization number to get addresses for

Responses

Response samples

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

Search external organization registry

Proxy queries to the Norwegian organization registry aka. "enhetsregisteret".

scopes:

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

An id that uniquely identifies the account.

query Parameters
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.

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.

name
string

Search for organization

organization_number
string

Search for organization

Responses

Response samples

Content type
application/json
[
  • {
    }
]

addresses

Search external postal place

Get postal place by country and postal code.

scopes:

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

An id that uniquely identifies the account.

country
required
string

ISO 3166-1 country code

postal_code
required
string

Postal code

Responses

Response samples

Content type
application/json
{
  • "country": "NO",
  • "postal_code": "0349",
  • "postal_place": "Oslo"
}

Validate address

Validate the given address and return close matching alternative suggestions if the provided address was most likely wrong.

scopes:

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

An id that uniquely identifies the account.

country
required
string

ISO 3166-1 country code

Request Body schema: application/json

Address information, including the name of the address, the postal code, the postal place (city where the address is in), and the country.

address_line
required
string
postal_place
required
string
country
required
string <iso-3166-1>

ISO 3166-1 country code

postal_code
required
string
address_line_2
string

Responses

Request samples

Content type
application/json
{
  • "address_line": "Sommerkroveien 34",
  • "address_line_2": "PB 123",
  • "postal_code": "0349",
  • "postal_place": "Oslo",
  • "country": "NO"
}

Response samples

Content type
application/json
{
  • "valid": false,
  • "alternatives": [
    ]
}