openapi: 3.0.0 info: title: Customers API description: > API for managing customers # Changelog All notable changes to the API. ## 2026-02-13 > **new**: Add endpoint for searching organization subunits (branches). > Extended organization search to include `underenheter` (subunits) information in the response. > Currently supports Norway (`no`) organization lookups. > - [GET /search/external/organizations/{country}/{organization_number}/subunits](/customers-api/organizations/aid_get_external_organization_subunits) > - [GET /search/external/organizations/{country}/{organization_number}](/customers-api/organizations/aid_get_external_organizations) ## 2025-07-01 > **new**: Extend `marketing_consent` for customer user to support custom consents > - [POST /customers/users](/customers-api/users/aid_customers_post) ## 2024-09-01 > **new**: Make country parameter dynamic and add support for Denmark. > - [GET /search/external/organizations/no (renamed to GET /search/external/organizations/{country})](/extension-api/organizations/aid_search_external_organizations_country) ## 2024-03-01 > **doc**: Improve description for customer `enrolled_by` type, add > examples > - [POST /customers/users](/customers-api/users/aid_customers_post) ## 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 > - [POST /customers/users](/customers-api/users/aid_customers_post) > - [PUT /customers/users/{customer_id}](/customers-api/users/aid_customers_cid_put) > - [GET /v1/accounts/{aid}/customers/users?type=contact](/customers-api/users/aid_customers_get) ## 2023-09-01 > **new**: Add endpoint for validating a given address and returning close matching alternatives if found. > - [POST /v1/accounts/{aid}/search/external/address/{country}/validate](/customers-api/addresses/aid_search_external_validate_address) ## 2020-12-01 > Add endpoint for getting multiple addresses for given organization number. > - [GET /search/external/organizations/{country}/{organization_number}](/customers-api/organizations/aid_get_external_organizations) ## 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 > - [PUT /customers/settings](http://localhost:8080/customers-api/settings/aid_customers_atributes_put) ## 2021-03-01 > Support new [customer](customer) type `other`. > - [POST /customers/users](/customers-api/users/aid_customers_post) > - [PUT /customers/users/{customer_id}](/customers-api/users/aid_customers_cid_put) ## 2021-02-01 > Extend customer `enrolled_by.type` to allow any string value, not just `url`, > `store` and `custom`. > > - [POST /v1/accounts/{aid}/customers/users](/customers-api/users/aid_customers_post) > - [PUT /v1/accounts/{aid}/customers/users/{customer_id}](/customers-api/users/aid_customers_cid_put) > Add support for removing customer terms and `include_deleted` when getting > list of all terms. > > - [DELETE /v1/accounts/{aid}/customers/terms/{tid}](/customers-api/terms/aid_customers_terms_tid_delete) > - [GET /v1/accounts/{aid}/customers/terms/{tid}](/customers-api/terms/aid_customers_terms_get) ## 2021-01-01 > Add support for limited access to customer > details with `user:customers:/customer/details` > - [GET /v1/accounts/{aid}/customers/users/{customer_id}](/customers-api/users/aid_customers_cid_get) > > Add support for logging on without MFA even if configured with MFA > - [GET /v1/accounts/{aid}/customers/login](/customers-api/password/aid_customers_login_post) ## 2020-12-01 > **new** Support filter users with `type` query parameter. > - [GET /v1/accounts/{aid}/customers/users?type=company](/customers-api/users/aid_customers_get) ## 2020-11-01 > **new** Support filter user tokens with `include_deleted` query parameter. > - [GET /v1/accounts/{aid}/customers/users/{cid}/tokens?include_deleted=false](/customers-api/tokens/aid_customers_cid_tokens_get) > **new** Support filter and search on sales locations > - [GET /v1/accounts/{aid}/locations](/customers-api/locations/aid_locations_get) > **new** Extend SalesLocation with `address.latitude`, `address.longitude`, > `chain`, `mcc`, `gln` and `franchise`. The `account_id` will be included > in any SalesLocation responses. > - [GET /v1/accounts/{aid}/locations](/customers-api/locations/aid_locations_get) ## 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. > - [PUT /customers/settings](http://localhost:8080/customers-api/settings/aid_customers_atributes_put) ## 2020-04-01 > Adds proxy to enhetsregisteret. > - [GET /search/external/organizations/no/?name=dintero](#operation/aid_search_external_organizations_no) ## 2020-03-10 > Add support for `attributes_keys` and `attributes_values` query > parameters for filtering customer users > - [GET /customers/users?attributes_keys=key&attributes_values=value](/customers-api/users/aid_customers_get) ## 2020-02-28 > Add support for enabling automatic tokens when phone numbers or emails change > - [PUT /customers/settings](/customers-api/settings/aid_customers_atributes_put) ## 2019-09-31 > Extends settings with support for configuring > users `customer_id_format`. > - [PUT /customers/settings](/customers-api/settings/aid_customers_atributes_put) > Extends the TokenEvent definition with `expires_at > read only property. > Extends settings with support for configuring > token events expiry > - [PUT /customers/settings](/customers-api/settings/aid_customers_atributes_put) ## 2019-07-31 > Extend user Address, add support for `latitude`, > `longitude` and `comment` properties. > - [POST /customers/users](/customers-api/users/aid_customers_post) > - [PUT /customers/users/{customer_id}](/customers-api/users/aid_customers_cid_put) ## 2019-07-31 > Add new endpoint for deleting a tag > - [DELETE /customers/tags/{tag_id}](/customers-api/tags/aid_customers_tags_tid_delete) ## 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 > - [PUT /customers/users/{customer_id}](/customers-api/users/aid_customers_cid_put) ## 2019-01-31 > Support new customer type `employee`. > - [POST /customers/users](/customers-api/users/aid_customers_post) > - [PUT /customers/users/{customer_id}](/customers-api/users/aid_customers_cid_put) ## 2018-06-04 > Adding tokens to deleted customers will > now fail with BAD_REQUEST. > - [POST /customers/users/{customer_id}/tokens](/customers-api/tokens/aid_customers_cid_tokens_post) > 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.. > - [GET /customers/users/{customer_id}/tokens](/customers-api/tokens/aid_customers_cid_tokens_get) ## 2018-04-11 > Add support for `delete_token_events` parameter when > creating > - [POST /customers/users/{customer_id}/tokens](/customers-api/tokens/aid_customers_cid_tokens_post) > Add support for filtering token events by `since_datetime`. > - [GET /customers/tokens/events](/customers-api/tokens/aid_customers_tokens_events_get) > Delete customer and all tokens owed by the customer in one > request when using `delete_tokens` query parameter. > - [DELETE /customers/users/{customer_id}](/customers-api/users/aid_customers_cid_delete) > Token event status. The status in response will now be set > to `customer.status` if a customer with status is included > in the response. > - [POST /customers/tokens/events](/customers-api/tokens/aid_customers_tokens_events_post) ## 2018-02-15 > Add minimum length for token token_id/type/value > - [POST /customers/tokens/events](/customers-api/tokens/aid_customers_tokens_events_post) > - [DELETE /customers/tokens/events](/customers-api/tokens/aid_customers_tokens_events_delete) > - [POST /customers/users/uid/tokens](/customers-api/tokens/aid_customers_cid_tokens_post) > Add endpoint for GET/DELETE token events > - [DELETE /customers/tokens/events](/customers-api/tokens/aid_customers_tokens_events_delete) > - [GET /customers/tokens/events](/customers-api/tokens/aid_customers_tokens_events_get) ## 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 > - [POST /customers/tokens/events](/customers-api/tokens/aid_customers_tokens_events_post) contact: name: API Integration Support email: integration@dintero.com version: LATEST license: name: UNLICENSED url: https://dintero.com security: - JWT: [] paths: /accounts/{aid}/customers/change_password: post: summary: aid_customers_change_password description: | 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 operationId: aid_customers_change_password tags: - password x-scopes: - write:accounts:/auth/users parameters: - $ref: '#/components/parameters/accountId' requestBody: content: application/json: schema: type: object required: - audience - email - type properties: email: type: string audience: type: string description: | 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: type: string enum: - customer - company description: | user type to login, required as users with different type can share email required: true security: - JWT: [] responses: '204': description: Success '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Change password sidebarTitle: Change password /accounts/{aid}/customers/login: post: summary: aid_customers_login_post description: | 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 operationId: aid_customers_login_post tags: - password x-scopes: - write:accounts:/auth/users - write:accounts:/auth/users/no-mfa parameters: - $ref: '#/components/parameters/accountId' requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Auth' - required: - password properties: password: type: string minLength: 4 maxLength: 255 description: > 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 description: credentials required: true security: - JWT: [] responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/AccessToken' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Login with email/password sidebarTitle: Login with email/password /accounts/{aid}/customers/mfa_login: post: summary: aid_customers_mfa_login_post description: > 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 operationId: aid_customers_mfa_login_post tags: - password x-scopes: - write:accounts:/auth/users parameters: - $ref: '#/components/parameters/accountId' requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/MFAAuth' - required: - secret properties: secret: type: string description: | The customers pin or password. description: credentials required: true security: - JWT: [] responses: '200': description: MFA login challenge content: application/json: schema: $ref: '#/components/schemas/MultiFactorAuthenticationChallenge' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Login with MFA sidebarTitle: Login with MFA /accounts/{aid}/customers/mfa_login_recovery: post: summary: aid_customers_mfa_login_initiate_recovery_post description: > 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 operationId: aid_customers_mfa_login_initiate_recovery_post tags: - password x-scopes: - write:accounts:/auth/users parameters: - $ref: '#/components/parameters/accountId' requestBody: content: application/json: schema: $ref: '#/components/schemas/MFAAuth' required: true security: - JWT: [] responses: '200': description: Recovery MFA challenge content: application/json: schema: $ref: >- #/components/schemas/MultiFactorAuthenticationRecoveryChallenge '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: MFA recovery sidebarTitle: MFA recovery /accounts/{aid}/customers/settings: get: operationId: aid_customers_atributes_get summary: aid_customers_atributes_get description: | Get customers settings scopes: - admin:customers - read:customers - public:customers parameters: - $ref: '#/components/parameters/accountId' tags: - settings x-scopes: - admin:customers - read:customers - public:customers security: - JWT: [] responses: '200': description: an object of customers settings content: application/json: schema: $ref: '#/components/schemas/CustomersSettings' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Customers settings sidebarTitle: Customers settings put: operationId: aid_customers_atributes_put summary: aid_customers_atributes_put description: | Update customers settings scopes: - admin:customers - write:customers tags: - settings x-scopes: - admin:customers - write:customers parameters: - $ref: '#/components/parameters/accountId' requestBody: content: application/json: schema: $ref: '#/components/schemas/CustomersSettings' description: customers settings required: true security: - JWT: [] responses: '200': description: added/updated object of customers settings content: application/json: schema: allOf: - $ref: '#/components/schemas/CustomersSettings' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Update settings sidebarTitle: Update settings /accounts/{aid}/customers/tags: get: operationId: aid_customers_tags_get summary: aid_customers_tags_get description: | Get all customer tags (also known as groups). scopes: - admin:customers - read:customers parameters: - $ref: '#/components/parameters/accountId' tags: - tags x-scopes: - admin:customers - read:customers security: - JWT: [] responses: '200': description: Customers Tags content: application/json: schema: type: array items: $ref: '#/components/schemas/CustomerTag' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Tags collection sidebarTitle: Tags collection post: operationId: aid_customers_tags_post summary: aid_customers_tags_post description: | Create a tag scopes: - admin:customers - write:customers tags: - tags x-scopes: - admin:customers - write:customers parameters: - $ref: '#/components/parameters/accountId' requestBody: content: application/json: schema: $ref: '#/components/schemas/CustomerTag' description: customer tag add required: true security: - JWT: [] responses: '200': description: Customers Tags content: application/json: schema: $ref: '#/components/schemas/CustomerTag' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Create new Tag sidebarTitle: Create new Tag /accounts/{aid}/customers/tags/{tag_id}: delete: operationId: aid_customers_tags_tid_delete summary: aid_customers_tags_tid_delete description: | Delete a tag. A deleted tag is removed from customer tags scopes: - admin:customers - write:customers parameters: - $ref: '#/components/parameters/accountId' - name: tag_id description: | tag id in: path required: true schema: type: string format: uuid tags: - tags x-scopes: - admin:customers - write:customers security: - JWT: [] responses: '200': description: Tag deleted content: application/json: schema: $ref: '#/components/schemas/CustomerTag' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Delete Tag sidebarTitle: Delete Tag /accounts/{aid}/customers/terms: post: operationId: aid_customers_terms_post summary: aid_customers_terms_post description: | Create customer terms and conditions scopes: - admin:customers - write:customers tags: - terms x-scopes: - admin:customers - write:customers parameters: - $ref: '#/components/parameters/accountId' requestBody: content: application/json: schema: $ref: '#/components/schemas/TermsAndConditions' description: terms to create required: true security: - JWT: [] responses: '200': description: Term created content: application/json: schema: $ref: '#/components/schemas/TermsAndConditions' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Create new Terms sidebarTitle: Create new Terms get: operationId: aid_customers_terms_get summary: aid_customers_terms_get description: | Get all customer terms and conditions scopes: - admin:customers - read:customers - public:customers tags: - terms x-scopes: - admin:customers - read:customers - public:customers parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/startingAfter' - name: include_deleted description: | include deleted terms in the response in: query schema: type: boolean default: false security: - JWT: [] responses: '200': description: Terms collection content: application/json: schema: type: array items: $ref: '#/components/schemas/TermsAndConditions' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Terms collection sidebarTitle: Terms collection /accounts/{aid}/customers/terms/{tid}: get: operationId: aid_customers_terms_tid_post summary: aid_customers_terms_tid_post description: | Get single terms and conditions scopes: - admin:customers - read:customers - public:customers tags: - terms x-scopes: - admin:customers - read:customers - public:customers parameters: - $ref: '#/components/parameters/accountId' - name: tid description: terms id in: path required: true schema: type: string format: uuid security: - JWT: [] responses: '200': description: Term details content: application/json: schema: $ref: '#/components/schemas/TermsAndConditions' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Terms details sidebarTitle: Terms details delete: operationId: aid_customers_terms_tid_delete summary: aid_customers_terms_tid_delete description: | Delete the customer term scopes: - admin:customers - write:customers tags: - terms x-scopes: - admin:customers - write:customers parameters: - $ref: '#/components/parameters/accountId' - name: tid description: terms id in: path required: true schema: type: string format: uuid security: - JWT: [] responses: '200': description: Deleted term content: application/json: schema: $ref: '#/components/schemas/TermsAndConditions' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Delete Term sidebarTitle: Delete Term /accounts/{aid}/customers/tokens/events: get: operationId: aid_customers_tokens_events_get summary: aid_customers_tokens_events_get description: | Get the token events scopes: - admin:customers - read:customers parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/startingAfter' - name: since_datetime description: > 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. in: query schema: type: string format: date-time - name: deleted_since description: | return only token events that has been deleted in: query schema: type: string format: date-time tags: - tokens x-scopes: - admin:customers - read:customers security: - JWT: [] responses: '200': description: events collection headers: page-count: description: | count object in response schema: type: integer content: application/json: schema: type: array items: type: object allOf: - properties: id: type: string readOnly: true description: | Auto-generated ID identifying the token type/value. status: type: string readOnly: true description: | The status resolved from latest events registered on given token type and value default: UNKNOWN example: DELETED events: type: array readOnly: true description: | Events recorded given token type and value example: - created_at: '2018-01-31T16:56:33Z' event: anonymous token status: PENDING - created_at: '2018-02-05T00:00:00Z' event: reqruited status: DELETED items: $ref: '#/components/schemas/TokenEvent' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' x-mint: metadata: title: Get token events sidebarTitle: Get token events delete: operationId: aid_customers_tokens_events_delete summary: aid_customers_tokens_events_delete description: | 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 parameters: - $ref: '#/components/parameters/accountId' requestBody: content: application/json: schema: type: object required: - token properties: token: $ref: '#/components/schemas/TokenTypeValue' event: description: Record an delete event, the status will be set to DELETED. type: object properties: event: type: string example: customer registered in webshop metadata: type: object required: true tags: - tokens x-scopes: - admin:customers - write:customers security: - JWT: [] responses: '204': description: events cleared x-mint: metadata: title: Delete token events sidebarTitle: Delete token events post: operationId: aid_customers_tokens_events_post summary: aid_customers_tokens_events_post description: | 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 tags: - tokens x-scopes: - admin:customers - write:customers parameters: - $ref: '#/components/parameters/accountId' requestBody: content: application/json: schema: type: object required: - token properties: token: $ref: '#/components/schemas/TokenTypeValue' event: $ref: '#/components/schemas/TokenEvent' required: true security: - JWT: [] responses: '200': description: Token details content: application/json: schema: $ref: '#/components/schemas/TokenDetail' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' x-mint: metadata: title: Find / Add token events sidebarTitle: Find / Add token events /accounts/{aid}/customers/users: post: summary: aid_customers_post description: | Create a new customer, `customer_id`, `email` and `phone_number` must be unique if specified. scopes: - admin:customers - write:customers - create:customers:/users operationId: aid_customers_post tags: - users x-scopes: - admin:customers - write:customers - create:customers:/users parameters: - $ref: '#/components/parameters/accountId' requestBody: content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/Customer' - properties: customer_id: type: string maxLength: 255 description: | 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: type: string minLength: 8 maxLength: 255 description: > The customer password. The caller must have scope `write:accounts:/auth/users` when password is included in the body pin: type: string minLength: 6 maxLength: 6 pattern: ^\d{6}$ description: > 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 description: customer to create required: true security: - JWT: [] responses: '200': description: Customer created content: application/json: schema: $ref: '#/components/schemas/CustomerResponse' '400': description: | Bad request - missing required fields or duplicate field detected content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Create new Customer sidebarTitle: Create new Customer head: summary: aid_customers_head description: > 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](/customers-api/settings/aid_customers_atributes_put) scopes: - admin:customers - read:customers - public:customers operationId: aid_customers_head tags: - users x-scopes: - admin:customers - read:customers - public:customers parameters: - $ref: '#/components/parameters/accountId' - name: email description: lookup customer by email in: query schema: type: string - name: phone_number description: lookup customer by phone_number in: query schema: type: string security: - JWT: [] responses: '200': description: Customer user exist headers: types: description: | The type of the user(s) matching the parameters. schema: type: string '404': description: No user match given query parameters content: application/json: schema: $ref: '#/components/schemas/Error' '405': description: Method not allowed by customer settings content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' x-mint: metadata: title: User exist sidebarTitle: User exist get: summary: aid_customers_get description: | 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 operationId: aid_customers_get tags: - users x-scopes: - admin:customers - read:customers parameters: - $ref: '#/components/parameters/accountId' - name: token_value description: lookup customers by token value in: query schema: type: string - name: token_type description: lookup customer by token type in: query schema: type: string - name: email description: lookup customer by email in: query schema: type: string - name: phone_number description: lookup customer by phone_number in: query schema: type: string - name: type description: lookup customer by type in: query schema: type: string enum: - customer - company - contact - employee - other - any - name: search description: | lookup customer where search term match name, phone number, customer_id or email. The search term will be matched with the user details in: query schema: type: string - name: tag_id description: lookup customers by tag id in: query schema: type: string - name: include_deleted description: | 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. in: query schema: type: boolean default: false - name: attributes_keys in: query description: | include customers that has all the attributes. style: form explode: false schema: type: array items: type: string maxItems: 4 - name: attributes_values in: query description: | Combine with `attributes_keys` to include customers with match on attribute values style: form explode: false schema: type: array items: type: string maxItems: 4 - name: since_datetime description: | 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 in: query schema: type: string format: date-time - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/startingAfter' - $ref: '#/components/parameters/total' security: - JWT: [] responses: '200': description: Customer collection headers: page-count: description: | count object in response schema: type: integer total-count: description: | total count, only set if query parameter `total` is set schema: type: integer content: application/json: schema: type: array items: $ref: '#/components/schemas/CustomerResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' x-mint: metadata: title: Customer collection sidebarTitle: Customer collection /accounts/{aid}/customers/users/{customer_id}: get: operationId: aid_customers_cid_get summary: aid_customers_cid_get description: | Customer details scopes: - admin:customers - read:customers - user:customers - user:customers:/customer/details parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/customerId' tags: - users x-scopes: - admin:customers - read:customers - user:customers - user:customers:/customer/details security: - JWT: [] responses: '200': description: Customer content: application/json: schema: $ref: '#/components/schemas/CustomerResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Customer details sidebarTitle: Customer details put: operationId: aid_customers_cid_put summary: aid_customers_cid_put description: | Update customer properties, properties not included in the body will remain unchanged. scopes: - admin:customers - write:customers - user:customers tags: - users x-scopes: - admin:customers - write:customers - user:customers parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/customerId' requestBody: content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/BasicUser' - properties: password: type: string minLength: 8 maxLength: 255 description: > The customer password. The caller must have scope `write:accounts:/auth/users` when password is included in the body pin: type: string minLength: 6 maxLength: 6 pattern: ^\d{6}$ description: > 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 description: Customer update required: true security: - JWT: [] responses: '200': description: Customer updated content: application/json: schema: $ref: '#/components/schemas/CustomerResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Update Customer sidebarTitle: Update Customer delete: operationId: aid_customers_cid_delete summary: aid_customers_cid_delete description: | Delete single customer scopes: - admin:customers - write:customers - user:customers tags: - users x-scopes: - admin:customers - write:customers - user:customers parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/customerId' - name: delete_tokens description: | Delete all tokens owned by the customer in: query schema: type: boolean default: false security: - JWT: [] responses: '200': description: Customer deleted content: application/json: schema: $ref: '#/components/schemas/CustomerResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Delete customer sidebarTitle: Delete customer /accounts/{aid}/customers/users/{customer_id}/change_customer_id: post: operationId: aid_customers_cid_change_customer_id_post summary: aid_customers_cid_change_customer_id_post description: | 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 tags: - users x-scopes: - admin:customers - admin:accounts parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/customerId' requestBody: content: application/json: schema: type: object properties: customer_id: type: string maxLength: 255 minLength: 1 description: | New customer_id (must not have trailing or leading spaces). description: Customer update required: true security: - JWT: [] responses: '200': description: Customer updated content: application/json: schema: $ref: '#/components/schemas/CustomerResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Change customer_id sidebarTitle: Change customer_id /accounts/{aid}/customers/users/{customer_id}/communication: get: operationId: aid_customers_cid_verify_get summary: aid_customers_cid_verify_get description: | Get the status of customer email / phone_number communication scopes: - admin:customers - read:customers - user:customers parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/customerId' tags: - communication x-scopes: - admin:customers - read:customers - user:customers security: - JWT: [] responses: '200': description: Customer email / phone_number communication status content: application/json: schema: allOf: - $ref: '#/components/schemas/Communication' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Customer email/phone_number Status sidebarTitle: Customer email/phone_number Status /accounts/{aid}/customers/users/{customer_id}/communication/{operation}/{field}: post: operationId: aid_customers_cid_verify_post summary: aid_customers_cid_verify_post description: | 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 tags: - communication x-scopes: - admin:customers - write:customers - user:customers parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/customerId' - name: field description: field to verify in: path required: true schema: type: string enum: - email - phone_number - name: operation description: Verify operation in: path required: true schema: type: string enum: - send-verification-code - confirm-verification-code requestBody: content: application/json: schema: type: object properties: code: description: | Verification code sent to customer type: string description: verification code security: - JWT: [] responses: '204': description: No content '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Verify Customer email/phone_number sidebarTitle: Verify Customer email/phone_number /accounts/{aid}/customers/users/{customer_id}/tags: put: operationId: aid_customers_cid_tags_put summary: aid_customers_cid_tags_put description: | Update Customer Tags scopes: - admin:customers - write:customers - user:customers tags: - tags x-scopes: - admin:customers - write:customers - user:customers parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/customerId' requestBody: content: application/json: schema: type: array items: type: string format: uuid description: list of tag ids description: tag ids to set required: true security: - JWT: [] responses: '200': description: Customer Data content: application/json: schema: type: array items: $ref: '#/components/schemas/CustomerTag' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Update Customer Tags sidebarTitle: Update Customer Tags get: operationId: aid_customers_cid_tags_get summary: aid_customers_cid_tags_get description: | Get tags for a customer scopes: - admin:customers - read:customers - user:customers parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/customerId' tags: - tags x-scopes: - admin:customers - read:customers - user:customers security: - JWT: [] responses: '200': description: Customer tags content: application/json: schema: type: array items: $ref: '#/components/schemas/CustomerTag' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Tag collection sidebarTitle: Tag collection /accounts/{aid}/customers/users/{customer_id}/tokens: get: operationId: aid_customers_cid_tokens_get summary: aid_customers_cid_tokens_get description: | Get all tokens for a Customer scopes: - admin:customers - read:customers - user:customers tags: - tokens x-scopes: - admin:customers - read:customers - user:customers parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/customerId' - name: type description: filter tokens on type in: query schema: type: string - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/startingAfter' - $ref: '#/components/parameters/total' - name: include_deleted description: | include deleted tokens in the response. in: query schema: type: boolean default: true security: - JWT: [] responses: '200': description: Token collection headers: page-count: description: | count object in response schema: type: integer total-count: description: | total count, only set if query parameter `total` is set schema: type: integer content: application/json: schema: type: array items: $ref: '#/components/schemas/CustomerToken' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Token collections sidebarTitle: Token collections post: operationId: aid_customers_cid_tokens_post summary: aid_customers_cid_tokens_post description: | Create a new customer token scopes: - admin:customers - write:customers - user:customers tags: - tokens x-scopes: - admin:customers - write:customers - user:customers parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/customerId' - name: delete_token_events description: | delete all token events recorded on token type/value before creating new customer token in: query schema: type: boolean default: false requestBody: content: application/json: schema: type: object allOf: - properties: token_id: type: string maxLength: 255 minLength: 1 description: | 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. readOnly: false - $ref: '#/components/schemas/CustomerToken' description: customer token to add required: true security: - JWT: [] responses: '201': description: Customer token added content: application/json: schema: $ref: '#/components/schemas/CustomerToken' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Create new Token sidebarTitle: Create new Token /accounts/{aid}/customers/users/{customer_id}/tokens/{tid}: delete: operationId: aid_customers_cid_tokens_tid_delete summary: aid_customers_cid_tokens_tid_delete description: | Delete Token scopes: - admin:customers - write:customers - user:customers tags: - tokens x-scopes: - admin:customers - write:customers - user:customers parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/customerId' - name: tid description: | The token id you have defined for the token. (must not have trailing or leading spaces) in: path required: true schema: type: string maxLength: 255 security: - JWT: [] responses: '200': description: Token deleted content: application/json: schema: allOf: - $ref: '#/components/schemas/CustomerToken' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Delete customer token sidebarTitle: Delete customer token /accounts/{aid}/locations: get: operationId: aid_locations_get summary: aid_locations_get description: > Get all sales locations, the starting_after have to be set to location_id scopes: - admin:locations - read:locations tags: - locations x-scopes: - admin:locations - read:locations parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/startingAfter' - name: search in: query description: | lookup locations where search term match name, phone_number, email, organization_number and business_name schema: type: string - name: status in: query description: | filter locations by status explode: true schema: type: array items: type: string - name: country in: query description: | filter locations by country explode: true schema: type: array items: type: string - name: phone_number in: query description: | filter locations by phone_number explode: true schema: type: array items: type: string - name: organization_number in: query description: | filter locations by organization_number explode: true schema: type: array items: type: string - name: email in: query description: | filter locations by email explode: true schema: type: array items: type: string - name: type in: query description: | filter locations by type explode: true schema: type: array items: type: string security: - JWT: [] responses: '200': description: SalesLocation collection content: application/json: schema: type: array items: $ref: '#/components/schemas/SalesLocationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Locations collection sidebarTitle: Locations collection post: operationId: aid_location_post summary: aid_location_post description: | Create a sales location scopes: - admin:locations - write:locations tags: - locations x-scopes: - admin:locations - write:locations parameters: - $ref: '#/components/parameters/accountId' requestBody: content: application/json: schema: allOf: - properties: location_id: type: string maxLength: 255 description: > 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 example: S01923 readOnly: false - $ref: '#/components/schemas/SalesLocation' description: location to create required: true security: - JWT: [] responses: '200': description: created an location content: application/json: schema: $ref: '#/components/schemas/SalesLocationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Create new sales location sidebarTitle: Create new sales location /accounts/{aid}/locations/{lid}: get: operationId: aid_locations_lid_get summary: aid_locations_lid_get description: | Get single sales location scopes: - admin:locations - read:locations parameters: - $ref: '#/components/parameters/accountId' - name: lid description: location id in: path required: true schema: type: string maxLength: 255 tags: - locations x-scopes: - admin:locations - read:locations security: - JWT: [] responses: '200': description: a single sales location details content: application/json: schema: $ref: '#/components/schemas/SalesLocationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Location details sidebarTitle: Location details put: operationId: aid_location_lid_put summary: aid_location_lid_put description: | Update location properties scopes: - admin:locations - write:locations tags: - locations x-scopes: - admin:locations - write:locations parameters: - $ref: '#/components/parameters/accountId' - name: lid description: location id in: path required: true schema: type: string maxLength: 255 requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/SalesLocation' description: Location update required: true security: - JWT: [] responses: '200': description: Location updated content: application/json: schema: allOf: - $ref: '#/components/schemas/SalesLocationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Update Sales location sidebarTitle: Update Sales location delete: operationId: aid_location_lid_delete summary: aid_location_lid_delete description: | Delete single location scopes: - admin:locations - write:locations parameters: - $ref: '#/components/parameters/accountId' - name: lid description: location id in: path required: true schema: type: string maxLength: 255 tags: - locations x-scopes: - admin:locations - write:locations security: - JWT: [] responses: '200': description: Location deleted content: application/json: schema: allOf: - $ref: '#/components/schemas/SalesLocationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Delete location sidebarTitle: Delete location /accounts/{aid}/search/external/organizations/{country}/{organization_number}: get: operationId: aid_get_external_organizations summary: aid_get_external_organizations description: | scopes: - public security: - JWT: [] parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/country' - name: organization_number description: Organization number to get addresses for in: path required: true schema: type: string tags: - organizations responses: '200': description: Organization search result collection content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/GetExternalOrganizationResult' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: >- Get addresses for organization number from external organization registry sidebarTitle: >- Get addresses for organization number from external organization registry /accounts/{aid}/search/external/organizations/{country}/{organization_number}/subunits: get: operationId: aid_get_external_organization_subunits summary: aid_get_external_organization_subunits description: > scopes: - public Get an organization's registered subunits. Proxies queries to respective registers. Currently only Norway (`no`) organization numbers are supported. security: - JWT: [] parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/country' - name: organization_number description: Organization number in: path required: true schema: type: string tags: - organizations responses: '200': description: Organization's subunits content: application/json: schema: type: array items: $ref: '#/components/schemas/GetExternalOrganizationSubunitsResult' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Get organization subunits sidebarTitle: Get organization subunits /accounts/{aid}/search/external/postal_place/{country}/{postal_code}: get: operationId: aid_search_external_postal_place summary: aid_search_external_postal_place description: | Get postal place by country and postal code. scopes: - public security: - JWT: [] parameters: - $ref: '#/components/parameters/accountId' - name: country description: | ISO 3166-1 country code in: path required: true schema: type: string - name: postal_code description: | Postal code in: path required: true schema: type: string tags: - addresses responses: '200': description: Result with postal_place content: application/json: schema: $ref: '#/components/schemas/PostalPlaceResult' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Search external postal place sidebarTitle: Search external postal place /accounts/{aid}/search/external/address/{country}/validate: post: operationId: aid_search_external_validate_address summary: aid_search_external_validate_address description: | Validate the given address and return close matching alternative suggestions if the provided address was most likely wrong. scopes: - public security: - JWT: [] parameters: - $ref: '#/components/parameters/accountId' - name: country description: | ISO 3166-1 country code in: path required: true schema: type: string requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Address' - required: - postal_code description: > Address information, including the name of the address, the postal code, the postal place (city where the address is in), and the country. tags: - addresses responses: '200': description: Result with close matching alternative addresses if found. content: application/json: schema: $ref: '#/components/schemas/AddressValidationResult' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Validate address sidebarTitle: Validate address /accounts/{aid}/customers/company/departments: get: operationId: aid_company_departments_get summary: aid_company_departments_get description: | List all departments register by company customers scopes: - admin:customers - read:customers - public:customers tags: - company x-scopes: - admin:customers - read:customers - public:customers parameters: - $ref: '#/components/parameters/accountId' - name: organization_number in: query required: true schema: type: string security: - JWT: [] responses: '200': description: company departments content: application/json: schema: type: array items: type: object properties: organization_number: type: string example: 123456789MVA departments: type: array example: - Production - Research and Development - Accounting and Finance items: type: string '400': $ref: '#/components/responses/BadRequest' x-mint: metadata: title: Get departments sidebarTitle: Get departments /accounts/{aid}/search/external/organizations/{country}: get: operationId: aid_search_external_organizations_country summary: aid_search_external_organizations_country description: > Proxy queries to the Norwegian or Danish organization registry. Please note that the only supported countries currently are "no" (Norway) and "dk" (Denmark). scopes: - public security: - JWT: [] parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/startingAfter' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/country' - name: name description: Search for organization in: query required: false schema: type: string - name: organization_number description: Search for organization in: query required: false schema: type: string tags: - organizations responses: '200': description: Organization search result collection content: application/json: schema: type: array items: $ref: '#/components/schemas/SearchExternalOrganizationResult' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/ServerError' x-mint: metadata: title: Search external organization registry sidebarTitle: Search external organization registry x-tagGroups: - name: customers tags: - users - tokens - password - communication - tags - terms - settings - name: saleslocations tags: - locations - name: external lookup tags: - organizations - addresses servers: - url: https://api.dintero.com/v1 components: parameters: accountId: name: aid description: | An id that uniquely identifies the account. in: path required: true schema: type: string format: ^[PT]{1}\d{8}$ minLength: 9 maxLength: 9 limit: name: limit in: query description: | A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items. schema: type: integer minimum: 1 maximum: 100 default: 10 startingAfter: name: starting_after in: query description: | 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. required: false schema: type: string total: name: total in: query description: | include `total-count` header in the response required: false schema: type: boolean default: false customerId: name: customer_id description: | The customer id you have defined for the customer. (must not have trailing or leading spaces) in: path required: true schema: type: string maxLength: 255 country: name: country description: | ISO 3166-1 country code in: path required: true schema: type: string responses: BadRequest: description: Bad / Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' AccessForbidden: description: Access forbidden, invalid JWT token was used content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' ServerError: description: Unexpected Error content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Resource was not found content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: Too Many Requests headers: Retry-After: description: | Indicates how long the user agent should wait in seconds before making a follow-up request. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: JWT: type: http description: > Bearer authentication (token authentication) should be used for accessing the API. Use [Get Token](/api-reference/authenticate/aid_auths_oauth_token_post) to get an access token for client credentials. Pass the token in the request header: Authorization: Bearer {access_token} where the **access_token** is JSON Web Tokens (JWT). scheme: bearer bearerFormat: JWT schemas: HMAC-SHA256: type: object description: HMAC-SHA-256 allOf: - $ref: '#/components/schemas/AutoTokenType' - required: - secret properties: secret: type: string description: > Use the secret to compute HMAC SHA256 digest of the source value. SHA256: type: object description: SHA-256 allOf: - $ref: '#/components/schemas/AutoTokenType' Error: type: object required: - error properties: error: type: object required: - message properties: code: type: string description: The code used to identify the error/warning errors: type: array description: The nested error(s) encountered during validation items: type: object message: type: string description: The human readable description of the error/warning Auth: type: object required: - audience - type properties: email: type: string description: | **Required** if `ident_type` and `ident` is not set ident_type: type: string description: | **Required** if `email` is not set enum: - phone_number - email ident: type: string description: | Email or phone_number, depending on the `ident_type`. **Required** if `email` is not set. audience: type: string description: | 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: type: string enum: - customer - company description: | user type to login, required as users with different type can share email AccessToken: type: object required: - access_token - token_type - expires_in properties: access_token: type: string description: A JWT access token example: eyJhbGci...t7P4 token_type: type: string enum: - Bearer expires_in: type: integer description: | The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated. example: 86400 refresh_token: type: string description: | Token that can be used to request new tokens when the existing Access Token expire. You can only get a Refresh Token if the Access Token used in the request has scope: - `create:accounts:auth:refresh_token` and the `grant-type` is one of: - `authorization_code` - `password` **NOTE**: - A Single-Page Application should not ever receive a Refresh Token, this information is sensitive and should not be exposed client-side in a browser. - Refresh token must be stored securely by an application since they allow a user to remain authenticated essentially forever. MFAAuth: type: object required: - audience - ident_type - ident - type properties: ident_type: type: string enum: - phone_number - email ident: type: string description: | Email or phone_number, depending on the `ident_type`. audience: type: string description: | 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: type: string enum: - customer - company description: | user type to login, required as users with different type can share email MultiFactorAuthenticationChallenge: type: object required: - links - mfa_token - challenge_type properties: links: type: array items: type: object required: - rel - href properties: rel: type: string enum: - mfa_challenge - mfa_oob href: type: string example: - rel: mfa_challenge href: >- https://test.dintero.com/v1/accounts/T11223351/auth/mfa/challenge - rel: mfa_oob href: https://test.dintero.com/v1/accounts/T11223351/auth/token mfa_token: description: MFA challenge token type: string challenge_type: description: > MFA challenge types - `oob` (out of band) means that the user will get an out of band message containing a `binding_code` that will have to be submitted along with the `mfa_token` when answering the mfa challenge type: string enum: - oob oob_channel: type: string enum: - sms - email description: | The channel to use for OOB MultiFactorAuthenticationRecoveryChallenge: type: object required: - links - mfa_token - oob_code - challenge_type properties: links: type: array items: type: object required: - rel - href properties: rel: type: string enum: - mfa_oob href: type: string binding_method: type: string enum: - prompt oob_code: type: string example: bkaiew...akas mfa_token: type: string challenge_type: description: > MFA challenge types - `oob` (out of band) means that the user will get an out of band message containing a `recovery_code` that will have to be submitted along with the `recovery_token` when answering the MFA recovery challenge. type: string enum: - oob CustomersMfaSettings: type: object description: enable mfa login required: - enabled - login - login_recovery properties: enabled: type: boolean description: > Use this setting to enable mfa for customers login. When mfa is enabled the mfa_login endpoint has to be used for logging in. default: false login: type: object description: mfa login required: - challenge_type - oob_channel properties: challenge_type: type: string enum: - oob oob_channel: type: string enum: - sms - email login_recovery: type: object description: mfa login recovery required: - challenge_type - oob_channel properties: challenge_type: type: string enum: - oob oob_channel: type: string enum: - sms - email AutoTokenType: type: object discriminator: propertyName: type required: - type properties: type: type: string enum: - SHA256 - HMAC-SHA256 CustomersSettings: type: object description: | Customer settings for the account properties: users: type: object description: | customers user configurations required: - customer_id_format properties: head: type: object description: > Enable endpoint [HEAD /customers/users endpoint](/customers-api/users/aid_customers_head) required: - enabled properties: enabled: type: boolean default: false phone_number_validation: type: object description: | Configuration validation of user phone_number required: - allow_duplicates properties: allow_duplicates: type: boolean default: false description: > Allow multiple users to share the same phone number. Passwordless login with OTP sent via SMS is not supported when enabled. customer_id_format: type: string description: > Format used when generating a customer_id when new user is created. - **uuid**: customer_id generated will be a random UUID - **sequence**: customer_id generated will be serial. The initial start value will be the current maximum + 1 of existing customer_ids. > **Note**: New customers should not be created with customer_id set when `sequence` format is used as it can introduce conflicts later when creating user without specifying customer_id enum: - uuid - sequence default: uuid mfa: $ref: '#/components/schemas/CustomersMfaSettings' verifications: type: object description: | Enable verifications on user updates. properties: phone_number: description: | Require verification to update user phone_number type: string enum: - sms auto_tokens: type: object description: | Automatically generate tokens for these properties on the customer properties: phone_number: type: array items: $ref: '#/components/schemas/AutoTokenType' email: type: array items: $ref: '#/components/schemas/AutoTokenType' tokens: type: object description: | tokens configuration properties: event_expiry: type: array description: | configure the expire behaviour of token events items: type: object required: - status - time_to_live properties: status: description: | the event status to configure TTL on type: string example: OPT_OUT time_to_live: type: integer example: 15780000 description: > Time-To-Live (TTL) for for the token event status in seconds attributes: type: array description: user attributes items: type: object required: - name - type properties: name: type: string description: name of the attribute type: type: string description: type of the attribute value enum: - string - integer - real - boolean - phonenumber - email - date - date-time multiple_values: type: boolean description: | agreement (true/false) to enter multiple values default: false private: type: boolean description: | agreement (true/false) for visibility for customers default: false Entity: type: object properties: id: type: string format: uuid description: | An UUID that uniquely identifies the resource readOnly: true created_at: type: string format: date-time description: | The date-time when the resource was created readOnly: true created_by: type: string example: 1c92f7e1-2897-4d46-bdcc-c127a914fb4e description: | The ID of the user/client created the resource readOnly: true updated_at: type: string format: date-time description: | The date-time when the resource was last updated readOnly: true deleted_by: type: string example: 1c92f7e1-2897-4d46-bdcc-c127a914fb4e description: | The ID of the user/client created the resource readOnly: true deleted_at: type: string format: date-time readOnly: true CustomerTag: allOf: - $ref: '#/components/schemas/Entity' - required: - tag properties: tag: type: string description: tag value example: VIP metadata: type: object description: | A set of key/value pairs that you can attach to a tag. TermsAndConditions: allOf: - $ref: '#/components/schemas/Entity' - required: - terms properties: terms: type: string TokenEvent: type: object description: | 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 required: - event properties: expires_at: type: string format: date-time readOnly: true created_at: type: string format: date-time readOnly: true event: type: string description: context about the event example: customer declined signup in store status: type: string description: | State to set on given token type and value example: OPT_OUT metadata: type: object description: | Additional metadata about the event example: store_id: SID1234 TokenTypeValue: type: object description: Lookup by token type and value required: - type - value properties: type: type: string minLength: 1 value: description: | identifies how or who is resposible for the token value type: string minLength: 1 CustomerData: type: object allOf: - properties: metadata: type: object maxProperties: 40 description: | 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 example: dob_year: 1985 UserConsent: type: object properties: consent: type: boolean example: true updated_at: readOnly: true type: string format: date-time example: '2018-01-12T13:42:00Z' description: | The date-time when the resource was last updated: Address: type: object required: - address_line - postal_place - country properties: address_line: type: string example: Sommerkroveien 34 address_line_2: type: string example: PB 123 postal_code: type: string example: '0349' postal_place: type: string example: Oslo country: type: string format: iso-3166-1 description: | ISO 3166-1 country code example: 'NO' CustomerAddress: description: Customer's addresses allOf: - $ref: '#/components/schemas/Address' - properties: latitude: type: number example: 59.942112 longitude: type: number example: 10.716991 type: type: string description: The address type enum: - custom - home - other - work custom_type: type: string description: | If the address `type` is `custom`, this property contains the custom value comment: type: string description: | Comment about the address example: 5th floor, use doorbell. CustomerTerm: type: object properties: id: type: string format: uuid accepted_at: type: string format: date-time readOnly: true BasicUser: type: object properties: first_name: example: John nullable: true type: string last_name: example: Doe nullable: true type: string email: description: | 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 example: customer@example.com nullable: true type: string phone_number: description: | A phone number in E.164 number formatting. format: ^\+?[1-9]\d{1,14}$ example: '+4799999999' nullable: true type: string attributes: type: object description: | Custom attributes status: description: Status of the customer nullable: true type: string favorite_store: description: customer favorite store nullable: true type: string enrolled_by: type: object required: - value description: The source that recruited the customer properties: type: type: string description: | Enrollment type, e.g. `url`, `store`, `qr_code`, any string example: url value: example: https://facebook.com nullable: true type: string marketing_consent: type: object description: Customers consent for marketing in different channels maxProperties: 10 properties: sms: $ref: '#/components/schemas/UserConsent' email: $ref: '#/components/schemas/UserConsent' additionalProperties: $ref: '#/components/schemas/UserConsent' type: type: string enum: - customer - company - contact - employee - other description: > 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` default: customer addresses: type: array items: $ref: '#/components/schemas/CustomerAddress' term: $ref: '#/components/schemas/CustomerTerm' company: type: object required: - bussiness_name description: | Company details, supported when type is Company properties: organization_number: type: string description: Companys identification number example: 123456789MVA bussiness_name: type: string example: TKP tech AS department: type: string description: companys department example: sales department industry: type: string example: computer industry website: type: string number_of_employees: type: string gender: example: male nullable: true type: string date_of_birth: format: date example: '1990-09-20' nullable: true type: string contact_for: type: array description: | The users that it is a contact for, supported when type is `contact` items: type: object required: - customer_id properties: customer_id: type: string description: | The customer id that it is a contact for Customer: type: object allOf: - $ref: '#/components/schemas/CustomerData' - $ref: '#/components/schemas/Entity' - $ref: '#/components/schemas/BasicUser' - required: - type properties: type: type: string enum: - customer - company - contact - employee - other default: customer CustomerResponse: allOf: - $ref: '#/components/schemas/Customer' - required: - customer_id properties: customer_id: type: string maxLength: 255 description: | 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. readOnly: true CustomerToken: allOf: - $ref: '#/components/schemas/Entity' - required: - type - value properties: token_id: type: string maxLength: 255 minLength: 1 description: | The token id you have defined for the token. (must not have trailing or leading spaces) readOnly: true type: type: string minLength: 1 description: | identifies how or who is resposible for the token value example: sha1:email value: type: string minLength: 1 example: a1b79ef1a62d94ffa86b3f3d846df0ee3993af92 metadata: type: object description: | Additional metadata about the token or the entity the token was created from example: exp_month: 10 exp_year: 20 mask_pan: '**** **** **** 3477' TokenDetail: type: object properties: id: type: string readOnly: true description: | Auto-generated ID identifying the token type/value. Will be random until the token type/value has been added to a customer or a token event has been registered. customer: type: object readOnly: true description: | The customer (if any) that the token belongs to allOf: - $ref: '#/components/schemas/CustomerResponse' token: type: object readOnly: true description: | The token (if any) that is found given token type and value allOf: - $ref: '#/components/schemas/CustomerToken' status: type: string readOnly: true description: | Aggregated status from events registered or customer resolved. The status will be set to `customer.status` and fallback to the status of the latest event. The status will be set to `UNKNOWN` if no `customer.status` and event status is registered. The status will be set to the previous event status (or UNKNOWN) if the event has expired default: UNKNOWN example: OPT_OUT events: type: array readOnly: true description: Events recorded given token type and value items: $ref: '#/components/schemas/TokenEvent' Communication: type: object allOf: - $ref: '#/components/schemas/Entity' - properties: communication: type: object properties: email: type: object properties: verified_at: type: string format: date-time description: email verified by verification code readOnly: true allowed: type: boolean readOnly: true phone_number: type: object properties: verified_at: type: string format: date-time readOnly: true description: phone_number verified by verification code allowed: type: boolean readOnly: true SalesLocation: type: object allOf: - $ref: '#/components/schemas/Entity' - properties: location_id: type: string maxLength: 255 description: | 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 example: S01923 readOnly: true name: type: string description: >- The location's trade name which is shown to its customers (receipt/signs) example: TKP Store timezone: type: string description: The location's timezone (IANA Timezone) example: Europe/Oslo status: type: string description: The location's status example: Active language_code: type: string description: | Language code of the localized company info, as defined by BCP 47 (IETF BCP 47, "Tags for Identifying Languages"). currency: type: string example: NOK description: | The three-character ISO-4217 currency. https://en.wikipedia.org/wiki/ISO_4217 phone_number: type: string description: | A phone number in E.164 number formatting. format: ^\+?[1-9]\d{1,14}$ example: '+4799999999' chain: type: string example: SuperChain email: type: string example: saleslocation@example.com mcc: type: string format: iso-18245 description: | A four-digit Merchant Category Code (MCC) for the store [ISO 18245:2003](https://www.iso.org/standard/33365.html) example: '5814' minimum: 4 maximum: 4 gln: type: string description: Company Global Location Number organization_number: type: string description: Company identification number example: 123456789MVA business_name: type: string description: The location's legal name example: TKP technology AS franchise: description: The location is part of a franchise. type: string example: Subway type: type: string description: The location type (Physical, Mobile) website_url: type: string description: The location's website address: allOf: - $ref: '#/components/schemas/Address' - properties: latitude: type: number longitude: type: number SalesLocationResponse: allOf: - properties: account_id: type: string format: ^[PT]{1}\d{8}$ minLength: 9 maxLength: 9 - $ref: '#/components/schemas/SalesLocation' GetExternalOrganizationResult: type: object required: - organization_number - business_name properties: organization_number: type: string description: Company identification number example: 123456789MVA business_name: type: string description: The location's legal name example: TKP technology AS business_address: $ref: '#/components/schemas/Address' registry_address: $ref: '#/components/schemas/Address' office_type: type: string description: head_office, branch or other type of office example: - head_office - branch GetExternalOrganizationSubunitsResult: type: object required: - organization_number - business_name properties: organization_number: type: string description: Company identification number example: 123456789MVA business_name: type: string description: The location's legal name example: TKP technology AS business_address: allOf: - $ref: '#/components/schemas/Address' description: The physical location address where the business operates registry_address: allOf: - $ref: '#/components/schemas/Address' description: >- The official registered postal address, may differ from physical location phone_number: type: string description: A phone number in E.164 number formatting example: '+4799999999' email: type: string format: email description: Email address example: contact@example.com website_url: type: string format: uri description: Website URL example: https://example.com PostalPlaceResult: type: object required: - country - postal_code - postal_place properties: country: type: string description: | ISO 3166-1 country code example: 'NO' postal_code: type: string example: '0349' postal_place: type: string example: Oslo AddressValidationResult: type: object required: - valid - alternatives properties: valid: type: boolean description: | If the address was valid or not. example: false alternatives: type: array description: | Close matching alternative addresses. items: type: object allOf: - $ref: '#/components/schemas/Address' - required: - postal_code SearchExternalOrganizationResult: type: object required: - response_from - organization_type - organization_number - business_name properties: response_from: type: string enum: - enhetsregisteret - cvr - underenheter example: enhetsregisteret organization_type: type: string example: AS description: | A code or string specifying the type of organization. phone_number: type: string description: | A phone number in E.164 number formatting. format: ^\+?[1-9]\d{1,14}$ example: '+4799999999' email: type: string example: hello@company.com organization_number: type: string description: Company identification number. example: 123456789MVA business_name: type: string description: The location's legal name. example: TKP technology AS business_address: $ref: '#/components/schemas/Address' registry_address: $ref: '#/components/schemas/Address' website_url: type: string description: The company's website.