The Company API from Smart Pension — 3 operation(s) for company.
openapi: 3.2.0
info:
title: Keystone Company API
version: v12
description: This is the endpoint description of Keystone API.
servers:
- url: https://api.sandbox.autoenrolment.co.uk
- url: /
tags:
- name: Company
paths:
/companies:
post:
summary: Companies/Create
tags:
- Company
parameters: []
requestBody:
content:
application/json:
examples:
valid_request:
value:
name: name
registration_number: '123'
legal_structure: Limited Company
signatories:
- email: john@doe.fr
forename: forename
surname: surname
scheme_detail:
tax_relief_basis_type: net_pay_arrangement
scheme_id: 256
automatic_linking_with_adviser:
value:
name: name
registration_number: '123'
legal_structure: Limited Company
signatories:
- email: john@doe.fr
forename: forename
surname: surname
scheme_detail:
tax_relief_basis_type: net_pay_arrangement
scheme_id: 257
adviser_token: qxuMdn24G5xw6L5pB3mE
invalid_parameters:
value:
name: name
registration_number: ''
legal_structure: Other
signatories:
- email: ''
forename: ''
surname: ''
two_signatories_have_same_emails:
value:
name: name
registration_number: '123'
legal_structure: Limited Company
signatories:
- email: banana@doe.fr
forename: forename
surname: surname
scheme_detail:
tax_relief_basis_type: net_pay_arrangement
admins:
- email: banana@doe.fr
forename: forename
surname: surname
schema:
type: object
properties:
scheme_origin:
type: string
enum:
- standard
scheme_origin_provider_id:
type: string
scheme_origin_provider_name:
type: string
name:
type: string
minimum: 2
maximum: 115
registration_number:
type: string
legal_structure:
type: string
tax_office_employer_reference:
type: string
minimum: 2
maximum: 50
tax_office_number:
type: string
minimum: 2
maximum: 30
reg_address1:
type: string
reg_address2:
type: string
reg_address3:
type: string
reg_address4:
type: string
reg_address_postcode:
type: string
minimum: 2
maximum: 255
reg_address_country_code:
type: string
trading_address1:
type: string
maximum: 140
trading_address2:
type: string
minimum: 2
maximum: 180
trading_address3:
type: string
minimum: 2
maximum: 65
trading_address4:
type: string
trading_address_postcode:
type: string
minimum: 2
maximum: 255
trading_address_country_code:
type: string
state_of_incorporation:
type: string
taxed_as:
type: string
tax_year_end_day:
type: integer
tax_year_end_month:
type: integer
national_insurance_saving_share:
type: number
pensionable_earning_type:
type: string
enum:
- banded
- unbanded
- tier1
- tier2
- tier3
pension_regulator_letter_code:
type: string
default_percentage:
type: number
signatories:
type: array
items:
type: object
properties:
date_of_birth:
type: string
title:
type: string
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
email:
type: string
password:
type: string
referee_id:
type: string
referee_type:
type: string
enum:
- customer
- employee
line1:
type: string
line2:
type: string
city:
type: string
county:
type: string
postcode:
type: string
required:
- forename
- surname
- email
admins:
type: array
items:
type: object
properties:
title:
type: string
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
email:
type: string
referee_id:
type: string
referee_type:
type: string
enum:
- customer
- employee
password:
type: string
required:
- forename
- surname
- email
scheme_details:
type: array
items:
type: object
properties:
starts_on:
type: string
renewal_on:
type: string
regulator_reference:
type: string
revenue_reference:
type: string
scheme_id:
type: integer
display_name:
type: string
tax_relief_basis_type:
type: string
tax_relief_fallback_type:
type: string
salary_sacrifice_consent_type:
type: string
enum:
- implied
- express
fund_set_id:
type: integer
fund_set_name:
type: string
instrument_name:
type: string
instrument_type:
type: string
assessment_required:
type: string
enum:
- not_applicable
- 'yes'
- 'no'
metadata:
type: object
ae_qualifying:
type: boolean
scheme_starts_on:
type: string
enrolment_event_on:
type: string
adviser_token: {}
incorporated_on:
type: string
employee_can_change_contribution:
type: boolean
required:
- name
- legal_structure
responses:
'201':
description: Success - automatic linking with an Adviser
content:
application/json:
examples:
valid_request:
value:
id: 203
name: name
slug: name
registration_number: '123'
tax_office_number: null
tax_office_employer_reference: null
legal_structure: Limited Company
welcome_letters_reminder_sent_at: null
pension_regulator_letter_code: null
trading_address1: null
trading_address2: null
trading_address3: null
trading_address_postcode: null
trading_address_country: null
reg_address1: null
reg_address2: null
reg_address3: null
reg_address4: null
reg_address_postcode: null
reg_address_country: null
pensionable_earning_type: unbanded
default_percentage: 3
created_at: '2026-08-05T12:58:47.000+01:00'
updated_at: '2026-08-05T12:58:47.000+01:00'
state: active
employee_can_change_contribution: true
uuid: 6ec55a05-c592-4c96-9d1e-773cf7ac6b2c
external_id: null
incorporated_on: null
layout_configuration_id: null
relief_at_source_active: false
only_employer_manages_membership: false
national_insurance_saving_share: 0
tax_relief_basis_type: net_pay_arrangement
tax_relief_fallback_type: null
direct_debit_optional: false
authorization_redirect_uri: https://id.host.com/customer/callbacks/smartpension?code=BLuSdugYlaItOCGcblM83tK7gouOzRrq3XyCKCcKK5A
signatories:
- intercom_user_id: cus90
intercom_user_id_hash: 831ee4169263b428cbe7ec194a53bec1d303a752f36211d8f67061f1bb28d95b
id: 90
email: john@doe.fr
reset_password_sent_at: null
remember_created_at: null
last_sign_in_at: null
slug: 21182ab1f2fd67e5
created_at: '2026-08-05T12:58:47.000+01:00'
updated_at: '2026-08-05T12:58:47.000+01:00'
gauth_enabled: false
gauth_tmp: null
forename: forename
surname: surname
title: null
authentication_token: ys7b-EUbFZm6BP-N1p8z
date_of_birth: null
line2: null
city: null
county: null
building_name: null
postcode: null
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:47.000+01:00'
gender: Male
role: signatory
middlename: null
envelope_state: ignition
enforce_password: true
company_id: 203
country_code: null
uuid: f168c0a0-88d3-4ea5-a16b-faa1e77d2167
preferred_locale: null
smart_analytics_access_permitted: false
links:
- rel: company
title: company
href: https://api.host.com/companies/203
admins: []
automatic_linking_with_adviser:
value:
id: 204
name: name
slug: name
registration_number: '123'
tax_office_number: null
tax_office_employer_reference: null
legal_structure: Limited Company
welcome_letters_reminder_sent_at: null
pension_regulator_letter_code: null
trading_address1: null
trading_address2: null
trading_address3: null
trading_address_postcode: null
trading_address_country: null
reg_address1: null
reg_address2: null
reg_address3: null
reg_address4: null
reg_address_postcode: null
reg_address_country: null
pensionable_earning_type: unbanded
default_percentage: 3
created_at: '2026-08-05T12:58:47.000+01:00'
updated_at: '2026-08-05T12:58:47.000+01:00'
state: active
employee_can_change_contribution: true
uuid: 984ee943-257c-4bdd-ba36-99caf8f11166
external_id: null
incorporated_on: null
layout_configuration_id: null
relief_at_source_active: false
only_employer_manages_membership: false
national_insurance_saving_share: 0
tax_relief_basis_type: net_pay_arrangement
tax_relief_fallback_type: null
direct_debit_optional: false
authorization_redirect_uri: https://id.host.com/customer/callbacks/smartpension?code=kvin0rXOaORihf7EW5lXMb_rqjROS7i4NebCBx1Vu6k
signatories:
- intercom_user_id: cus91
intercom_user_id_hash: 63c2d817837a5f81686f12580c4173fd3d4f3143f38038c872eaf4d42ef6a5d7
id: 91
email: john@doe.fr
reset_password_sent_at: null
remember_created_at: null
last_sign_in_at: null
slug: 7dd4016fe360ec60
created_at: '2026-08-05T12:58:47.000+01:00'
updated_at: '2026-08-05T12:58:47.000+01:00'
gauth_enabled: false
gauth_tmp: null
forename: forename
surname: surname
title: null
authentication_token: 1Zeb6fA2Bh3it5theK8q
date_of_birth: null
line2: null
city: null
county: null
building_name: null
postcode: null
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:47.000+01:00'
gender: Male
role: signatory
middlename: null
envelope_state: ignition
enforce_password: true
company_id: 204
country_code: null
uuid: ae63eddd-18f3-468c-9047-3f111017fa8a
preferred_locale: null
smart_analytics_access_permitted: false
links:
- rel: company
title: company
href: https://api.host.com/companies/204
admins: []
schema:
$ref: '#/components/schemas/response_company'
'422':
description: When 2 signatories/admins have same emails
content:
application/json:
examples:
invalid_parameters:
value:
errors:
- code: 743
title: The Registration Number is too short.
detail: This company registration number is too short, please provide a valid company registration number.
meta:
count: 2
source:
pointer: /data/attributes/registration_number
- code: 703
title: Company registration number is a required field.
detail: You need to enter the company registration number. If the business is not registered with Companies House please use another unique number to identify this business. For example, HMRC registration number, business telephone number or charity number.
meta: {}
source:
pointer: /data/attributes/registration_number
- code: 1601
title: Forename is a required field.
detail: You need to include a forename for this signatory.
meta: {}
source:
pointer: /data/relationships/signatories/0/attributes/forename
- code: 1615
title: Surname is too short.
detail: You need to enter a surname with at least 2 characters.
meta:
count: 2
source:
pointer: /data/relationships/signatories/0/attributes/surname
- code: 1603
title: Surname is a required field.
detail: You need to include a surname for this signatory.
meta: {}
source:
pointer: /data/relationships/signatories/0/attributes/surname
- code: 1606
title: Email address is a required field.
detail: You need to include an email address for this signatory.
meta: {}
source:
pointer: /data/relationships/signatories/0/attributes/email
- code: 1607
title: Email address is not valid.
detail: 'The email address you entered is not valid. This may be because of the address format or the domain being unreachable. Make sure the address uses this format: name@something.com and that email is enabled for this domain.'
meta: {}
source:
pointer: /data/relationships/signatories/0/attributes/email
two_signatories_have_same_emails:
value:
errors:
- code: 732
title: There are duplications of emails.
detail: 'The emails that you provided are duplicated in multiple admins/signatories: banana@doe.fr.'
meta:
emails: banana@doe.fr
source:
pointer: /data
get:
summary: Companies/List
tags:
- Company
security:
- oAuth2:
- user
parameters:
- 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
name:
type: array
items:
type: string
state:
type: array
items:
type: string
scheme_detail:
type: object
properties:
starts_on:
type: string
scheme_details:
type: object
properties:
starts_on:
type: string
scheme:
type: object
properties:
category:
type: string
id:
type: integer
adviser_companies:
type: object
properties:
adviser_id:
type: integer
company_id:
type: integer
employees:
type: object
properties:
id:
type: integer
tax_relief_basis_type:
type: array
items:
type: string
required: false
style: deepObject
- name: include[]
in: query
schema:
type: array
items:
enum:
- company_automation
- scheme_detail
- scheme_details
- scheme
- adviser_companies
- customers
- employees
required: false
- 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: 0
links:
- rel: self
title: self
href: http://api.host.com/companies
- rel: first
title: first
href: http://api.host.com/companies?offset=0&limit=50
- rel: last
title: last
href: http://api.host.com/companies?offset=0&limit=50
companies: []
success_with_client_credentials_token:
value:
limit: 50
offset: 0
total: 0
links:
- rel: self
title: self
href: http://api.host.com/companies
- rel: first
title: first
href: http://api.host.com/companies?offset=0&limit=50
- rel: last
title: last
href: http://api.host.com/companies?offset=0&limit=50
companies: []
schema:
type: object
properties:
limit:
type:
- integer
- 'null'
offset:
type:
- integer
- 'null'
total:
type:
- integer
- 'null'
links:
type: array
items:
$ref: '#/components/schemas/link'
companies:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/response_company'
'401':
description: Unauthorized
content:
text/plain:
examples:
unauthorized:
value: 'HTTP Token: Access denied.
'
application/json:
examples:
unauthorized_with_client_credentials_token:
value: ''
/companies/{company_id}:
get:
summary: Companies/Get
tags:
- Company
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 1113
schema:
type: string
- name: include[]
in: query
schema:
type: array
items:
enum:
- company_automation
- benefit_groups
- payroll_configurations
- scheme_detail
- scheme_detail.company_tax_reliefs
- scheme_details
- employee
- envelope
- customers
- know_your_customer_data
- bank_account_details
- scheme
- scheme.bank_detail
- economic_zone
- adviser_companies
required: false
responses:
'200':
description: Success
content:
application/json:
examples:
success:
value:
id: 1110
name: eget eros 1569
slug: adipiscing-1166
registration_number: '1'
tax_office_number: ABC123
tax_office_employer_reference: ABC123
legal_structure: Limited Company
welcome_letters_reminder_sent_at: '2026-08-05T00:00:00.000+01:00'
pension_regulator_letter_code: '100'
trading_address1: 511 Mendota Alley
trading_address2: 5 Grover Plaza
trading_address3: 8 Fairview Hill
trading_address_postcode: '999'
trading_address_country: null
reg_address1: 72625 Fordem Center
reg_address2: 83 Del Sol Avenue
reg_address3: 26670 Swallow Hill
reg_address4: 14865 Warbler Park
reg_address_postcode: '888'
reg_address_country: null
pensionable_earning_type: unbanded
default_percentage: 3
created_at: '2026-08-05T13:03:24.000+01:00'
updated_at: '2026-08-05T13:03:24.000+01:00'
state: active
employee_can_change_contribution: true
uuid: 0960aa58-899e-4f97-af83-3b4cb1d8c861
external_id: null
incorporated_on: '2026-08-05'
layout_configuration_id: null
relief_at_source_active: false
only_employer_manages_membership: false
national_insurance_saving_share: null
tax_relief_basis_type: null
tax_relief_fallback_type: null
direct_debit_optional: false
success_with_client_credentials_token:
value:
id: 1113
name: volutpat convallis 1574
slug: venenatis-1169
registration_number: '1'
tax_office_number: ABC123
tax_office_employer_reference: ABC123
legal_structure: Limited Company
welcome_letters_reminder_sent_at: '2026-08-05T00:00:00.000+01:00'
pension_regulator_letter_code: '100'
trading_address1: 167 Mallard Crossing
trading_address2: 73 Truax Alley
trading_address3: 05189 Birchwood Crossing
trading_address_postcode: '999'
trading_address_country: null
reg_address1: 04461 Alpine Park
reg_address2: 9 Bellgrove Street
reg_address3: 86551 Dryden Drive
reg_address4: 2 Shoshone Alley
reg_address_postcode: '888'
reg_address_country: null
pensionable_earning_type: unbanded
default_percentage: 3
created_at: '2026-08-05T13:03:25.000+01:00'
updated_at: '2026-08-05T13:03:25.000+01:00'
state: active
employee_can_change_contribution: true
uuid: 95fdbb86-b0b5-40c6-83d4-4e122f4b23c2
external_id: null
incorporated_on: '2026-08-05'
layout_configuration_id: null
relief_at_source_active: false
only_employer_manages_membership: false
national_insurance_saving_share: null
tax_relief_basis_type: null
tax_relief_fallback_type: null
direct_debit_optional: false
schema:
$ref: '#/components/schemas/response_company'
'401':
description: Unauthorized
content:
text/plain:
examples:
unauthorized:
value: 'HTTP Token: Access denied.
'
application/json:
examples:
unauthorized_with_client_credentials_token:
value: ''
'404':
description: Not Found
put:
summary: Companies/Update
tags:
- Company
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 1412
schema:
type: string
requestBody:
content:
application/json:
examples:
success:
va
# --- truncated at 32 KB (111 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smart-pension/refs/heads/main/openapi/smart-pension-company-api-openapi.yml