The Customer API from Smart Pension — 4 operation(s) for customer.
openapi: 3.2.0
info:
title: Keystone Customer API
version: v12
description: This is the endpoint description of Keystone API.
servers:
- url: https://api.sandbox.autoenrolment.co.uk
- url: /
tags:
- name: Customer
paths:
/companies/{company_id}/customers:
post:
summary: Customers/Create
tags:
- Customer
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 207
schema:
type: string
requestBody:
content:
application/json:
examples:
valid_request:
value:
forename: Elsa
surname: Frozen
postcode: CH1 LLY
email: snow@gmail.com
date_of_birth: '1995-01-01'
invalid_parameter_request:
value:
forename: ''
surname: ''
postcode: ''
forbidden_request:
value:
forename: Elsa
surname: Frozen
postcode: CH1 LLY
email: snow@gmail.com
date_of_birth: '1995-01-01'
schema:
type: object
properties:
date_of_birth:
type: string
title:
type: string
enum:
- Mr
- Mrs
- Ms
- Miss
- Mx
- Dr
- Lord
- Lady
- Sir
- Prof
- Rev
- Captain
- Bursar
forename:
type: string
maximum: 100
x-ruby-regexp: (?-mix:\A[[:alpha:]\s‘’`'-]*\z)
middlename:
type: string
minimum: 2
maximum: 50
surname:
type: string
x-ruby-regexp: (?-mix:\A[[:alpha:]\s‘’`'-]*\z)
minimum: 2
maximum: 80
telephone:
type: string
alternative_telephone:
type: string
line1:
type: string
maximum: 140
line2:
type: string
minimum: 2
maximum: 180
city:
type: string
minimum: 2
maximum: 65
county:
type: string
minimum: 2
maximum: 75
postcode:
type: string
minimum: 2
maximum: 255
email:
type: string
minimum: 6
maximum: 70
building_name:
type: string
minimum: 2
maximum: 80
building_number:
type: string
maximum: 80
gender:
type: string
enum:
- Male
- Female
- Other
- Undeclared
country_code:
type: string
preferred_locale:
type: string
required:
- forename
- surname
- email
- date_of_birth
- postcode
responses:
'201':
description: Success
content:
application/json:
example:
intercom_user_id: cus95
intercom_user_id_hash: 94c52306a2ced55c529ce19233813bf762bdaf45b4a6570db01cd730447b7782
id: 95
email: snow@gmail.com
reset_password_sent_at: null
remember_created_at: null
last_sign_in_at: null
slug: 2aa7dcd24068a5ce
created_at: '2026-08-05T12:58:50.000+01:00'
updated_at: '2026-08-05T12:58:50.000+01:00'
gauth_enabled: false
gauth_tmp: null
forename: Elsa
surname: Frozen
title: null
authentication_token: wNSTquRTAFz_z9fLPGWh
date_of_birth: '1995-01-01'
line2: null
city: null
county: null
building_name: null
postcode: CH1 LLY
line1: null
building_number: null
telephone: null
alternative_telephone: null
referee_id: null
referee_type: null
referral_state: ignition
referral_clicks: 0
referral_reward_name: null
authentication_token_generated_at: '2026-08-05T12:58:50.000+01:00'
gender: Male
role: admin
middlename: null
envelope_state: ignition
enforce_password: true
company_id: 207
country_code: null
uuid: 962f1bcc-27cb-4227-b04e-98f590c080e9
preferred_locale: null
smart_analytics_access_permitted: false
links:
- rel: company
title: company
href: https://api.host.com/companies/207
schema:
$ref: '#/components/schemas/response_customer'
'403':
description: Forbidden number of customers (max 50)
'422':
description: Invalid parameters
get:
summary: Customers/List
tags:
- Customer
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 217
schema:
type: string
- name: limit
in: query
schema:
type: integer
required: false
- name: offset
in: query
schema:
type: integer
required: false
- name: sort
in: query
schema:
type: string
required: false
- name: direction
in: query
schema:
type: string
enum:
- ASC
- DESC
required: false
- name: filter
in: query
schema:
type: object
properties:
id:
type: array
items:
type: integer
referee_id:
type: array
items:
type: integer
role:
type: array
items:
type: string
envelope_state:
type: array
items:
type: string
forename:
type: array
items:
type: string
surname:
type: array
items:
type: string
email:
type: array
items:
type: string
required: false
style: deepObject
- name: operator
in: query
schema:
type: string
enum:
- or
- and
required: false
responses:
'200':
description: Success
content:
application/json:
examples:
success:
value:
limit: 50
offset: 0
total: 3
links:
- rel: self
title: self
href: http://api.host.com/companies/216/customers
- rel: first
title: first
href: http://api.host.com/companies/216/customers?offset=0&limit=50
- rel: last
title: last
href: http://api.host.com/companies/216/customers?offset=0&limit=50
customers:
- intercom_user_id: cus109
intercom_user_id_hash: 10c7b96956fe0fed49998515eb80e450379c6335cdb9099ad3c8ca94a528dbb9
id: 109
email: email_1@example.com
reset_password_sent_at: null
remember_created_at: null
last_sign_in_at: null
slug: f388b782dfa282c7
created_at: '2026-08-05T12:58:54.000+01:00'
updated_at: '2026-08-05T12:58:54.000+01:00'
gauth_enabled: false
gauth_tmp: null
forename: forename
surname: surname
title: null
authentication_token: bEHwZzHdLWxwV3TgsLps
date_of_birth: '2011-08-05'
line2: null
city: null
county: null
building_name: null
postcode: postcode
line1: null
building_number: null
telephone: '+447890123223'
alternative_telephone: null
referee_id: null
referee_type: null
referral_state: ignition
referral_clicks: 0
referral_reward_name: null
authentication_token_generated_at: '2026-08-05T12:58:54.000+01:00'
gender: Male
role: admin
middlename: null
envelope_state: ignition
enforce_password: true
company_id: 216
country_code: null
uuid: b721340c-6241-45f4-860f-04a5b671d341
preferred_locale: null
smart_analytics_access_permitted: false
links:
- rel: company
title: company
href: https://api.host.com/companies/216
- intercom_user_id: cus110
intercom_user_id_hash: 8d44ed306704db3d993822eb27b8877bd2ededfda8f2dd668e7f935a7c0a8e1f
id: 110
email: email_2@example.com
reset_password_sent_at: null
remember_created_at: null
last_sign_in_at: null
slug: 5021da6ed9f33aa5
created_at: '2026-08-05T12:58:54.000+01:00'
updated_at: '2026-08-05T12:58:54.000+01:00'
gauth_enabled: false
gauth_tmp: null
forename: forename
surname: surname
title: null
authentication_token: VnkUTVJzYdsSy38P59vo
date_of_birth: '2011-08-05'
line2: null
city: null
county: null
building_name: null
postcode: postcode
line1: null
building_number: null
telephone: '+447890123223'
alternative_telephone: null
referee_id: null
referee_type: null
referral_state: ignition
referral_clicks: 0
referral_reward_name: null
authentication_token_generated_at: '2026-08-05T12:58:54.000+01:00'
gender: Male
role: admin
middlename: null
envelope_state: ignition
enforce_password: true
company_id: 216
country_code: null
uuid: 1e26eafa-b892-46af-9e36-cdcdd268d5d1
preferred_locale: null
smart_analytics_access_permitted: false
links:
- rel: company
title: company
href: https://api.host.com/companies/216
- intercom_user_id: cus111
intercom_user_id_hash: 56cf950cfadb13d808c9421b2ed928504c18ac688425b47be8041494c1bb36bc
id: 111
email: wroberts@jabbersphere.mil
reset_password_sent_at: null
remember_created_at: null
last_sign_in_at: null
slug: 68LwEshE
created_at: '2026-08-05T12:58:54.000+01:00'
updated_at: '2026-08-05T12:58:54.000+01:00'
gauth_enabled: false
gauth_tmp: null
forename: Willie
surname: Wilson
title: Sir
authentication_token: null
date_of_birth: '2001-08-05'
line2: 86108 Arkansas Point
city: Brisbane
county: Nevada
building_name: Merry
postcode: '96642'
line1: 719 Armistice Road
building_number: '978'
telephone: null
alternative_telephone: null
referee_id: null
referee_type: null
referral_state: ignition
referral_clicks: 0
referral_reward_name: null
authentication_token_generated_at: null
gender: Male
role: admin
middlename: null
envelope_state: ignition
enforce_password: true
company_id: 216
country_code: gb
uuid: d5acb7fa-b66d-4f5d-8a3b-cdc5b33675ea
preferred_locale: null
smart_analytics_access_permitted: false
links:
- rel: company
title: company
href: https://api.host.com/companies/216
success_with_client_credentials_token:
value:
limit: 50
offset: 0
total: 2
links:
- rel: self
title: self
href: http://api.host.com/companies/217/customers
- rel: first
title: first
href: http://api.host.com/companies/217/customers?offset=0&limit=50
- rel: last
title: last
href: http://api.host.com/companies/217/customers?offset=0&limit=50
customers:
- intercom_user_id: cus112
intercom_user_id_hash: 942b78aa1b41bcdb96da27c101da2e779d2ee1da789e5865c83e35ba299de6ab
id: 112
email: email_1@example.com
reset_password_sent_at: null
remember_created_at: null
last_sign_in_at: null
slug: 573458a7b8ceece8
created_at: '2026-08-05T12:58:54.000+01:00'
updated_at: '2026-08-05T12:58:54.000+01:00'
gauth_enabled: false
gauth_tmp: null
forename: forename
surname: surname
title: null
authentication_token: 7zBxzyqJ7mLAkDotM-TH
date_of_birth: '2011-08-05'
line2: null
city: null
county: null
building_name: null
postcode: postcode
line1: null
building_number: null
telephone: '+447890123223'
alternative_telephone: null
referee_id: null
referee_type: null
referral_state: ignition
referral_clicks: 0
referral_reward_name: null
authentication_token_generated_at: '2026-08-05T12:58:54.000+01:00'
gender: Male
role: admin
middlename: null
envelope_state: ignition
enforce_password: true
company_id: 217
country_code: null
uuid: d88d1a4f-712c-49ce-b9e8-7b61499b42cf
preferred_locale: null
smart_analytics_access_permitted: false
links:
- rel: company
title: company
href: https://api.host.com/companies/217
- intercom_user_id: cus113
intercom_user_id_hash: 7ac2d340afbd655d66c0eb98492e444aafafcc0bccc453845185bb0926eb9dcd
id: 113
email: email_2@example.com
reset_password_sent_at: null
remember_created_at: null
last_sign_in_at: null
slug: 3e716e0b1c825d7c
created_at: '2026-08-05T12:58:54.000+01:00'
updated_at: '2026-08-05T12:58:54.000+01:00'
gauth_enabled: false
gauth_tmp: null
forename: forename
surname: surname
title: null
authentication_token: yuGrbBRQg9BMmK8KWxhz
date_of_birth: '2011-08-05'
line2: null
city: null
county: null
building_name: null
postcode: postcode
line1: null
building_number: null
telephone: '+447890123223'
alternative_telephone: null
referee_id: null
referee_type: null
referral_state: ignition
referral_clicks: 0
referral_reward_name: null
authentication_token_generated_at: '2026-08-05T12:58:54.000+01:00'
gender: Male
role: admin
middlename: null
envelope_state: ignition
enforce_password: true
company_id: 217
country_code: null
uuid: f0f2eaf6-534b-4283-b646-364a42cf4772
preferred_locale: null
smart_analytics_access_permitted: false
links:
- rel: company
title: company
href: https://api.host.com/companies/217
schema:
type: object
properties:
limit:
type:
- integer
- 'null'
offset:
type:
- integer
- 'null'
total:
type:
- integer
- 'null'
links:
type: array
items:
$ref: '#/components/schemas/link'
customers:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/response_customer'
'401':
description: Unauthorized
/companies/{company_id}/customers/{id}:
delete:
summary: Customers/Destroy
tags:
- Customer
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 210
schema:
type: string
- name: id
in: path
required: true
example: 103
schema:
type: string
responses:
'204':
description: Success
'403':
description: Forbidden when customer is a signatory
content:
application/json:
example:
errors:
- code: 279
title: You need to have at least one signatory.
detail: You need to have at least one signatory.
form: null
attribute: base
error: need_to_have_at_least_one_signatory
meta: {}
source:
pointer: /base
get:
summary: Customers/Get
tags:
- Customer
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 214
schema:
type: string
- name: id
in: path
required: true
example: 107
schema:
type: string
- name: include[]
in: query
schema:
type: array
items:
enum:
- company
- company.scheme_detail
- company.scheme_detail.company_tax_reliefs
- company.scheme_details
- company.know_your_customer_data
- company.payroll_configurations
- company.benefit_groups
- company.bank_account_details
- company.scheme
- company.scheme.bank_detail
- company.provider_scheme_migration
- company.economic_zone
- employee
- employee.contributions
- shortcut
required: false
responses:
'200':
description: Success
content:
application/json:
examples:
success:
value:
intercom_user_id: cus105
intercom_user_id_hash: 386198d1aac26dc9aedcdb5886562bc4b707eb5de85e910f51088677ded0c756
id: 105
email: jhall@gigazoom.edu
reset_password_sent_at: null
remember_created_at: null
last_sign_in_at: null
slug: qE9Qvc
created_at: '2026-08-05T12:58:51.000+01:00'
updated_at: '2026-08-05T12:58:51.000+01:00'
gauth_enabled: false
gauth_tmp: null
forename: Helen
surname: Hill
title: Dr
authentication_token: null
date_of_birth: '2001-08-05'
line2: 134 Delladonna Plaza
city: Calimesa
county: Oklahoma
building_name: Veith
postcode: '60673'
line1: 2470 Manufacturers Center
building_number: '37'
telephone: null
alternative_telephone: null
referee_id: null
referee_type: null
referral_state: ignition
referral_clicks: 0
referral_reward_name: null
authentication_token_generated_at: null
gender: Male
role: admin
middlename: null
envelope_state: ignition
enforce_password: true
company_id: 212
country_code: gb
uuid: 97c01042-618d-4dc2-8214-1f119ba867d7
preferred_locale: null
smart_analytics_access_permitted: false
links:
- rel: company
title: company
href: https://api.host.com/companies/212
success_with_client_credentials_token:
value:
intercom_user_id: cus107
intercom_user_id_hash: 74481f8661a77a962ca375d31c8784cdd9e59adb3788038013e1a75481c2d31e
id: 107
email: jkennedy@photobean.info
reset_password_sent_at: null
remember_created_at: null
last_sign_in_at: null
slug: VSnUOV
created_at: '2026-08-05T12:58:52.000+01:00'
updated_at: '2026-08-05T12:58:52.000+01:00'
gauth_enabled: false
gauth_tmp: null
forename: Ernest
surname: Knight
title: Dr
authentication_token: null
date_of_birth: '2001-08-05'
line2: 423 Briar Crest Way
city: Rancho Palos Verdes
county: Pennsylvania
building_name: Emmet
postcode: 74366-0508
line1: 7163 Norway Maple Parkway
building_number: '66'
telephone: null
alternative_telephone: null
referee_id: null
referee_type: null
referral_state: ignition
referral_clicks: 0
referral_reward_name: null
authentication_token_generated_at: null
gender: Male
role: signatory
middlename: null
envelope_state: ignition
enforce_password: true
company_id: 214
country_code: gb
uuid: f3adad46-9f5e-4aa9-a9bd-4da00a709b0e
preferred_locale: null
smart_analytics_access_permitted: false
links:
- rel: company
title: company
href: https://api.host.com/companies/214
schema:
$ref: '#/components/schemas/response_customer'
'401':
description: Unauthorized
'404':
description: Not Found
put:
summary: Customers/Update
tags:
- Customer
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 230
schema:
type: string
- name: id
in: path
required: true
example: 131
schema:
type: string
requestBody:
content:
application/json:
examples:
success:
value:
alternative_telephone: +44 123 4567 890
building_name: ''
building_number: '123'
city: London
company_id: 230
country_code: GB
county: Sussex
date_of_birth: '1986-11-12'
line1: Wellington Square
line2: The Palace
middlename: ''
postcode: ZE0 0ZZ
telephone: +44 123 4567 890
title: Mr
email: vduncan@vimbo.edu
forename: James
surname: Bond
password: '!1234Qwertyuiop'
invalid_parameters:
value:
alternative_telephone: +44 123 4567 890
building_name: ''
building_number: '123'
city: London
company_id: 232
country_code: GB
county: Sussex
date_of_birth: '1986-11-12'
line1: Wellington Square
line2: The Palace
middlename: ''
postcode: ZE0 0ZZ
telephone: +44 123 4567 890
title: Mr
email: ''
forename: James
surname: Bond
password: '!1234Qwertyuiop'
schema:
type: object
properties:
date_of_birth:
type: string
title:
type: string
enum:
- Mr
- Mrs
- Ms
- Miss
- Mx
- Dr
- Lord
- Lady
- Sir
- Prof
- Rev
- Captain
- Bursar
forename:
type: string
maximum: 100
x-ruby-regexp: (?-mix:\A[[:alpha:]\s‘’`'-]*\z)
middlename:
type: string
minimum: 2
maximum: 50
surname:
type: string
x-ruby-regexp: (?-mix:\A[[:alpha:]\s‘’`'-]*\z)
minimum: 2
maximum: 80
telephone:
type: string
alternative_telephone:
type: string
line1:
type: string
maximum: 140
line2:
type: string
minimum: 2
maximum: 180
city:
type: string
minimum: 2
maximum: 65
county:
type: string
minimum: 2
maximum: 75
postcode:
type: string
minimum: 2
maximum: 255
email:
type: string
minimum: 6
maximum: 70
building_name:
type: string
minimum: 2
maximum: 80
building_number:
type: string
maximum: 80
gender:
type: string
enum:
- Male
- Female
- Other
- Undeclared
country_code:
type: string
preferred_locale:
type: string
password:
type: string
current_password:
type: string
responses:
'204':
description: Success
'403':
description: Forbidden email update for signatory with unsigned envelope
content:
application/json:
example:
errors:
- code: 34
title: Company without envelope.
detail: The Participation Agreement cannot be generated because we are currently generating another one for the same company.
form: null
attribute: base
error: company_without_envelope
meta: {}
source:
pointer: /base
'422':
description: Invalid parameters
content:
application/json:
example:
errors:
- code: 936
title: Email is too short.
detail: You need to enter an email with at least 6 characters.
meta:
# --- truncated at 32 KB (110 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smart-pension/refs/heads/main/openapi/smart-pension-customer-api-openapi.yml