Currencycloud Contacts API
Create, search and manage the list of users that have access in your Currencycloud account or associated sub-accounts.
OpenAPI Specification
openapi: 3.0.3
info:
title: api-onboarding Account Usage Contacts API
version: v1
description: Create, search and manage the list of users that have access in your Currencycloud account or associated sub-accounts.
servers:
- url: /onboarding
description: Relative URL
- url: https://api.currencycloud.com/onboarding
description: Production server (uses live data)
- url: https://devapi.currencycloud.com/onboarding
description: Dev server (uses test data)
tags:
- name: Contacts
description: Create, search and manage the list of users that have access in your Currencycloud account or associated sub-accounts.
paths:
/contacts/current:
get:
tags:
- Contacts
x-api-group: manage
summary: Get Authenticating Contact
description: Gets the contact record for the authenticated user.
operationId: GetAuthenticatingContact
produces:
- application/json
parameters:
- name: X-Auth-Token
in: header
required: true
type: string
description: Authentication token
minLength: 32
responses:
'200':
description: Success.
schema:
$ref: '#/definitions/Contact'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'401':
description: Unauthorized.
x-errors:
- code: invalid_supplied_credentials
category: username
message: Authentication failed with the supplied credentials
params: ''
schema:
$ref: '#/definitions/UnauthorizedError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'404':
description: Resource not found.
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'429':
description: Too many requests.
x-errors:
- code: too_many_requests
category: base
message: Too many requests have been made to the api. Please refer to the Developer Center for more information
params: ''
schema:
$ref: '#/definitions/RateLimitError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'500':
description: Internal server error
x-errors:
- code: internal_server_error
category: base
message: Internal server error
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'503':
description: Service is temporary unavailable
x-errors:
- code: service_unavailable
category: base
message: Service is temporarily unavailable
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
default:
description: Unexpected error.
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
/contacts/find:
post:
tags:
- Contacts
x-api-group: manage
summary: Find Contacts
description: Returns contacts that match the parameters.
operationId: FindContactsPost
produces:
- application/json
parameters:
- name: X-Auth-Token
in: header
required: true
type: string
description: Authentication token
minLength: 32
- name: account_name
in: formData
required: false
type: string
description: Account name
pattern: \S+
minLength: 1
maxLength: 150
- name: account_id
in: formData
required: false
type: string
description: Sub-Account UUID
format: uuid
- name: first_name
in: formData
required: false
type: string
description: The contact's first name.
minLength: 1
maxLength: 100
- name: last_name
in: formData
required: false
type: string
description: The contact's last name.
minLength: 1
maxLength: 100
- name: email_address
in: formData
required: false
type: string
description: The contact's email address.
pattern: ^[\w\.\_\%\-\+]+@([\w-]+\.)+\w{2,}+$
minLength: 6
maxLength: 255
- name: your_reference
in: formData
required: false
type: string
description: User-generated reference code.
minLength: 1
maxLength: 255
- name: phone_number
in: formData
required: false
type: string
description: The contact's phone number.
minLength: 1
maxLength: 100
- name: login_id
in: formData
required: false
type: string
description: The contact's Currencycloud login ID.
minLength: 1
maxLength: 50
- name: status
in: formData
required: false
type: string
enum:
- enabled
- not_enabled
description: Contact status - "enabled" allows the contact to conduct activity on the sub-account, "not_enabled" disables the contact.
- name: locale
in: formData
required: false
type: string
description: Locale code ("en", "en-US", "fr-FR").
minLength: 2
maxLength: 5
- name: timezone
in: formData
required: false
type: string
description: Timezone ("Europe/London", "America/New_York").
minLength: 7
maxLength: 35
- name: page
in: formData
required: false
type: string
description: Page number
pattern: ^\d+$
- name: per_page
in: formData
required: false
type: string
description: Number of results per page.
pattern: ^\d+$
- name: order
in: formData
required: false
type: string
description: Any field name to change the sort order.
minLength: 1
maxLength: 255
- name: order_asc_desc
in: formData
required: false
type: string
enum:
- asc
- desc
default: asc
description: Sort records in ascending or descending order.
responses:
'200':
description: Success.
schema:
properties:
contacts:
type: array
items:
$ref: '#/definitions/Contact'
pagination:
$ref: '#/definitions/Pagination'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'400':
description: Client error.
schema:
$ref: '#/definitions/FindContactsError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'401':
description: Unauthorized.
x-errors:
- code: invalid_supplied_credentials
category: username
message: Authentication failed with the supplied credentials
params: ''
schema:
$ref: '#/definitions/UnauthorizedError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'404':
description: Resource not found.
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'429':
description: Too many requests.
x-errors:
- code: too_many_requests
category: base
message: Too many requests have been made to the api. Please refer to the Developer Center for more information
params: ''
schema:
$ref: '#/definitions/RateLimitError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'500':
description: Internal server error
x-errors:
- code: internal_server_error
category: base
message: Internal server error
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'503':
description: Service is temporary unavailable
x-errors:
- code: service_unavailable
category: base
message: Service is temporarily unavailable
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
default:
description: Unexpected error.
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
/contacts/{id}:
get:
tags:
- Contacts
x-api-group: manage
summary: Get Contact
description: Gets the contact for the given ID.
operationId: GetContact
produces:
- application/json
parameters:
- name: X-Auth-Token
in: header
required: true
type: string
description: Authentication token
minLength: 32
- name: id
in: path
required: true
type: string
description: Contact UUID
format: uuid
responses:
'200':
description: Success.
schema:
$ref: '#/definitions/Contact'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'400':
description: Client error.
x-errors:
- code: id_is_not_valid_uuid
category: id
message: id should be in UUID format
params: ''
- code: contact_not_found
category: id
message: Contact was not found for this id
params: ''
schema:
$ref: '#/definitions/GetContactError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'401':
description: Unauthorized.
x-errors:
- code: invalid_supplied_credentials
category: username
message: Authentication failed with the supplied credentials
params: ''
- code: first_name_invalid_format
category: first_name
message: Please make sure that first_name doesn't contain < or > symbols
params: ''
- code: last_name_invalid_format
category: last_name
message: Please make sure that last_name doesn't contain < or > symbols
params: ''
schema:
$ref: '#/definitions/UnauthorizedError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'404':
description: Resource not found.
schema:
$ref: '#/definitions/NotFoundError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'429':
description: Too many requests.
x-errors:
- code: too_many_requests
category: base
message: Too many requests have been made to the api. Please refer to the Developer Center for more information
params: ''
schema:
$ref: '#/definitions/RateLimitError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'500':
description: Internal server error
x-errors:
- code: internal_server_error
category: base
message: Internal server error
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'503':
description: Service is temporary unavailable
x-errors:
- code: service_unavailable
category: base
message: Service is temporarily unavailable
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
default:
description: Unexpected error.
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
post:
tags:
- Contacts
x-api-group: manage
summary: Update Contact
description: Updates an existing contact. Returns the updated contact entity on success.
operationId: UpdateContact
consumes:
- multipart/form-data
produces:
- application/json
parameters:
- name: X-Auth-Token
in: header
required: true
type: string
description: Authentication token
minLength: 32
- name: id
in: path
required: true
type: string
description: Contact UUID
format: uuid
- name: first_name
in: query
required: false
type: string
description: The contact's first name.
minLength: 1
maxLength: 100
- name: last_name
in: query
required: false
type: string
description: The contact's last name.
minLength: 1
maxLength: 100
- name: email_address
in: query
required: false
type: string
description: The contact's email address. A request to update a contact's email address does not immediately update the value. Instead, an email change request flow is initiated, sending notifications to both the old and new email addresses. The value will be updated when the change is confirmed via a link sent to the new email address.
pattern: ^[\w\.\_\%\-\+]+@([\w-]+\.)+\w{2,}+$
minLength: 6
maxLength: 255
- name: your_reference
in: query
required: false
type: string
description: User-generated reference code.
minLength: 1
maxLength: 255
- name: phone_number
in: query
required: false
type: string
description: The contact's phone number.
minLength: 1
maxLength: 100
- name: mobile_phone_number
in: query
required: false
type: string
description: The contact's mobile phone number.
minLength: 1
maxLength: 100
- name: login_id
in: query
required: false
type: string
description: The contact's Currencycloud login ID.
minLength: 1
maxLength: 50
- name: status
in: query
required: false
type: string
enum:
- enabled
- not_enabled
description: Contact status - "enabled" allows the contact to conduct activity on the sub-account, "not_enabled" disables the contact.
- name: locale
in: query
required: false
type: string
description: Locale code ("en", "en-US", "fr-FR").
minLength: 2
maxLength: 5
- name: timezone
in: query
required: false
type: string
description: Timezone ("Europe/London", "America/New_York").
minLength: 7
maxLength: 35
- name: date_of_birth
in: query
required: false
type: string
format: date
description: Contact's date of birth. ISO 8601 format YYYY-MM-DD. Required if account type is individual.
responses:
'200':
description: Success.
schema:
$ref: '#/definitions/Contact'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'400':
description: Client error.
x-errors:
- code: at_least_one_parameter
category: base
message: 'At least one parameter should be present: first_name, last_name, email_address, phone_number, mobile_phone_number, login_id, locale, timezone, status'
params: ''
- code: id_is_not_valid_uuid
category: id
message: id should be in UUID format
params: ''
- code: first_name_is_too_short
category: first_name
message: first_name cann ot be shorter than 1 character(s)
params: '{ "minlength" => 1 }'
- code: first_name_is_too_long
category: first_name
message: first_name can not be longer than 100 character(s)
params: '{ "maxlength" => 100 }'
- code: last_name_is_too_short
category: last_name
message: last_name can not be shorter than 1 character(s)
params: '{ "minlength" => 1 }'
- code: last_name_is_too_long
category: last_name
message: last_name can not be longer than 100 character(s)
params: '{ "maxlength" => 100 }'
- code: email_address_is_too_short
category: email_address
message: email_address can not be shorter than 1 character(s)
params: '{ "minlength" => 1 }'
- code: email_address_is_too_long
category: email_address
message: email_address can not be longer than 255 character(s)
params: '{ "maxlength" => 255 }'
- code: email_address_is_in_invalid_format
category: email_address
message: email_address is in invalid format
params: ''
- code: phone_number_is_too_short
category: phone_number
message: phone_number can not be shorter than 1 character(s)
params: '{ "minlength" => 1 }'
- code: phone_number_is_too_long
category: phone_number
message: phone_number can not be longer than 100 character(s)
params: '{ "maxlength" => 100 }'
- code: mobile_phone_number_is_too_short
category: mobile_phone_number
message: mobile_phone_number can not be shorter than 1 character(s)
params: '{ "minlength" => 1 }'
- code: mobile_phone_number_is_too_long
category: mobile_phone_number
message: mobile_phone_number can not be longer than 100 character(s)
params: '{ "maxlength" => 100 }'
- code: login_id_in_use
category: login_id
message: 'login_id already in use: john.smith@company.com'
params: ''
- code: login_id_is_too_long
category: login_id
message: login_id can not be longer than 50 character(s)
params: '{ "maxlength" => 50 }'
- code: locale_is_too_short
category: locale
message: locale can not be shorter than 2 character(s)
params: '{ "minlength" => 2 }'
- code: locale_is_too_long
category: locale
message: locale can not be longer than 5 character(s)
params: '{ "maxlength" => 5 }'
- code: timezone_is_too_short
category: timezone
message: timezone can not be shorter than 7 character(s)
params: '{ "minlength" => 7 }'
- code: timezone_is_too_long
category: timezone
message: timezone can not be longer than 35 character(s)
params: '{ "maxlength" => 35 }'
- code: status_not_in_range
category: status
message: 'status should be in range: enabled, not_enabled'
params: ''
- code: date_of_birth_type_is_wrong
category: date_of_birth
message: date_of_birth should be of date type
params: '{ "type" => "date" }'
- code: date_of_birth_is_required
category: date_of_birth
message: Date of Birth is a required field. Please provide date of birth (YYYY-MM-DD)
params: ''
- code: contact_not_found
category: id
message: Contact was not found for this id
params: ''
- code: editing_first_last_name_not_allowed
category: name
message: You cannot edit First and Last name. Please contact support for additional information
params: ''
schema:
$ref: '#/definitions/UpdateContactError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'401':
description: Unauthorized.
x-errors:
- code: invalid_supplied_credentials
category: username
message: Authentication failed with the supplied credentials
params: ''
- code: first_name_invalid_format
category: first_name
message: Please make sure that first_name doesn't contain < or > symbols
params: ''
- code: last_name_invalid_format
category: last_name
message: Please make sure that last_name doesn't contain < or > symbols
params: ''
schema:
$ref: '#/definitions/UnauthorizedError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'404':
description: Resource not found.
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'429':
description: Too many requests.
x-errors:
- code: too_many_requests
category: base
message: Too many requests have been made to the api. Please refer to the Developer Center for more information
params: ''
schema:
$ref: '#/definitions/RateLimitError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'500':
description: Internal server error
x-errors:
- code: internal_server_error
category: base
message: Internal server error
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'503':
description: Service is temporary unavailable
x-errors:
- code: service_unavailable
category: base
message: Service is temporarily unavailable
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
default:
description: Unexpected error.
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
/contacts/create:
post:
tags:
- Contacts
x-api-group: manage
summary: Create Contact
description: Creates a new contact and attaches it to a sub-account. Returns the new contact entity on success.
operationId: CreateContact
consumes:
- multipart/form-data
produces:
- application/json
parameters:
- name: X-Auth-Token
in: header
required: true
type: string
description: Authentication token
minLength: 32
- name: account_id
in: formData
required: true
type: string
description: Account UUID
format: uuid
- name: first_name
in: formData
required: true
type: string
description: The contact's first name.
minLength: 1
maxLength: 100
- name: last_name
in: formData
required: true
type: string
description: The contact's last name.
minLength: 1
maxLength: 100
- name: email_address
in: formData
required: true
type: string
description: The contact's email address.
pattern: ^[\w\.\_\%\-\+]+@([\w-]+\.)+\w{2,}+$
minLength: 6
maxLength: 255
- name: phone_number
in: formData
required: true
type: string
description: The contact's phone number.
minLength: 1
maxLength: 100
- name: your_reference
in: formData
required: false
type: string
description: User-generated reference code.
minLength: 1
maxLength: 255
- name: mobile_phone_number
in: formData
required: false
type: string
description: The contact's mobile phone number.
minLength: 1
maxLength: 100
- name: login_id
in: formData
required: false
type: string
description: The contact's Currencycloud login ID, allows the contact to login and conduct activity on the sub-account.
minLength: 1
maxLength: 50
- name: status
in: formData
required: false
type: string
enum:
- enabled
- not_enabled
description: Contact status - "enabled" allows the contact to conduct activity on the sub-account, "not_enabled" disables the contact.
- name: locale
in: formData
required: false
type: string
description: Locale code ("en", "en-US", "fr-FR").
minLength: 2
maxLength: 5
- name: timezone
in: formData
required: false
type: string
description: Timezone ("Europe/London", "America/New_York").
minLength: 7
maxLength: 35
- name: date_of_birth
in: formData
required: false
type: string
description: The contact's date of birth. ISO 8601 format YYYY-MM-DD. <b>Required if account type is individual</b>.
format: date
responses:
'200':
description: Success.
schema:
$ref: '#/definitions/Contact'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'400':
description: Client error.
x-errors:
- code: first_name_invalid_format
category: first_name
message: Please make sure that first_name doesn't contain < or > symbols
params: ''
- code: last_name_invalid_format
category: last_name
message: Please make sure that last_name doesn't contain < or > symbols
params: ''
- code: account_id_is_required
category: account_id
message: account_id is required
params: ''
- code: first_name_is_required
category: first_name
message: first_name is required
params: ''
- code: last_name_is_required
category: last_name
message: last_name is required
params: ''
- code: email_address_is_required
category: email_address
message: email_address is required
params: ''
- code: phone_number_is_required
category: phone_number
message: phone_number is required
params: ''
- code: account_id_is_not_valid_uuid
category: account_id
message: account_id should be in UUID format
params: ''
- code: first_name_is_too_short
category: first_name
message: first_name can not be shorter than 1 character(s)
params: '{ "minlength" => 1 }'
- code: first_name_is_too_long
category: first_name
message: first_name can not be longer than 100 character(s)
params: '{ "maxlength" => 100 }'
- code: last_name_is_too_short
category: last_name
message: last_name can not be shorter than 1 character(s)
params: '{ "minlength" => 1 }'
- code: last_name_is_too_long
category: last_name
message: last_name can not be longer than 100 character(s)
params: '{ "maxlength" => 100 }'
- code: email_address_is_too_short
category: email_address
message: email_address can not be shorter than 1 character(s)
params: '{ "minlength" => 1 }'
- code: email_address_is_too_long
category: email_address
message: email_address can not be longer than 255 character(s)
params: '{ "maxlength" => 255 }'
- code: email_address_is_in_invalid_format
category: email_address
message: email_address is in invalid format
params: ''
- code: phone_number_is_too_short
category: phone_number
message: phone_number can not be shorter than 1 character(s)
params: '{ "minlength" => 1 }'
- code: phone_number_is_too_long
category: phone_number
message: phone_number can not be longer than 100 character(s)
params: '{ "maxlength" => 100 }'
- code: mobile_phone_number_is_too_short
category: mobile_phone_number
message: mobile_phone_number can not be shorter than 1 character(s)
params: '{ "minlength" => 1 }'
- code: mobile_phone_number_is_too_long
category: mobile_phone_number
message: mobile_phone_number can not be longer than 100 character(s)
params: '{ "maxlength" => 100 }'
- code: login_id_is_too_short
category: login_id
message: login_id can not be shorter than 1 character(s)
params: '{ "minlength" => 1 }'
- code: login_id_in_use
category: login_id
message: login_id already in use
params: '{"field": "login_id"}'
- code: login_id_is_too_long
category: login_id
message: login_id can not be longer than 50 character(s)
params: '{ "maxlength" => 50 }'
- code: locale_is_too_short
category: locale
message: locale can not be shorter than 2 character(s)
params: '{ "minlength" => 2 }'
- code: locale_is_too_long
category: locale
message: locale can not be longer than 5 character(s)
params: '{ "maxlength" => 5 }'
- code: timezone_is_too_short
category: timezone
message: timezone can not be shorter than 7 character(s)
params: '{ "minlength" => 7 }'
- code: timezone_is_too_long
category: timezone
message: timezone can not be longer than 35 character(s)
params: '{ "maxlength" => 35 }'
- code: status_not_in_range
category: status
message: 'status should be in range: enabled, not_enabled.'
params: ''
- code: date_of_birth_type_is_wrong
category: date_of_birth
message: date_of_birth should be of date type.
params: '{ "type" => "date" }'
- code: date_of_birth_is_required
category: date_of_birth
message: Date of Birth is a required field. Please provide date of birth (YYYY-MM-DD)
params: ''
schema:
$ref: '#/definitions/CreateContactError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'401':
description: Unauthorized.
x-errors:
- code: invalid_supplied_credentials
category: username
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/currencycloud/refs/heads/main/openapi/currencycloud-contacts-api-openapi.yml