> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tilta.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Replace a person
> Fully replace an existing person record using PUT semantics. The addresses array is replaced entirely – include all entries you want to retain.
This endpoint performs a full replacement of a person record using HTTP `PUT` semantics. All fields are overwritten with the values you provide, and the `addresses` array is replaced in its entirety – any address entries not included in the new payload will be removed. Use this endpoint to correct identity data, update a person's name after a legal change, or refresh address history with a new current address. To update only specific fields, retrieve the current person first using the Retrieve person endpoint, make your changes to the returned payload, and submit the complete updated object to this endpoint.
This is a **full replacement** operation. The `addresses` array is replaced entirely – omitting an existing address entry will
permanently remove it. Always retrieve the current person record before calling this endpoint to avoid data loss.
Updating a person's identity data does not automatically trigger a new KYC check. If you update core identity fields (such as
name or date of birth) for a person who is already associated with an approved merchant, contact Tilta to determine whether
re-verification is required.
## OpenAPI
````yaml PUT /v1/persons/{external_id}
openapi: 3.0.0
info:
version: 0.0.1
title: Tilta API
description: Tilta API documentation
servers:
- url: https://api.tilta.io
description: Tilta Production API
- url: https://api.tilta-sandbox.io
description: Tilta Sandbox API
security: []
paths:
/v1/persons/{external_id}:
put:
tags:
- Merchants
summary: Replace a person
description: >-
Replaces a person. This is a full-replacement update: every field in the
request body must be provided.
Nullable fields may be cleared by sending `null` explicitly. The
`addresses` array is replaced entirely – send `[]` to clear all stored
addresses.
To change only a subset of fields, fetch the current person first and
submit the merged payload.
parameters:
- schema:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier of a person.
required: true
name: external_id
in: path
requestBody:
content:
application/json:
schema:
type: object
properties:
salutation:
type: string
nullable: true
enum:
- MR
- MS
- OTHER
description: Person salutation. Send `null` to clear.
first_name:
type: string
description: Person first name.
last_name:
type: string
description: Person last name.
birth_date:
type: number
nullable: true
description: Person date of birth. Send `null` to clear.
email:
type: string
nullable: true
format: email
description: Person email. Send `null` to clear.
phone:
type: string
nullable: true
description: Person phone number (+491711010101). Send `null` to clear.
example: '+491711010101'
is_fatca:
type: boolean
nullable: true
description: >-
Is the person a US taxpayer under FATCA reporting
obligations? Send `null` to clear.
is_pep:
type: boolean
nullable: true
description: >-
Is the person a Politically Exposed person (PEP)? Send
`null` to clear.
tax_id:
type: string
nullable: true
description: Person tax ID. Send `null` to clear.
citizenship:
type: array
nullable: true
items:
type: string
enum:
- AF
- AL
- DZ
- AS
- AD
- AO
- AI
- AQ
- AG
- AR
- AM
- AW
- AU
- AT
- AZ
- BS
- BH
- BD
- BB
- BY
- BE
- BZ
- BJ
- BM
- BT
- BO
- BQ
- BA
- BW
- BV
- BR
- IO
- BN
- BG
- BF
- BI
- CV
- KH
- CM
- CA
- KY
- CF
- TD
- CL
- CN
- CX
- CC
- CO
- KM
- CD
- CG
- CK
- CR
- HR
- CU
- CW
- CY
- CZ
- CI
- DK
- DJ
- DM
- DO
- EC
- EG
- SV
- GQ
- ER
- EE
- SZ
- ET
- FK
- FO
- FJ
- FI
- FR
- GF
- PF
- TF
- GA
- GM
- GE
- DE
- GH
- GI
- GR
- GL
- GD
- GP
- GU
- GT
- GG
- GN
- GW
- GY
- HT
- HM
- VA
- HN
- HK
- HU
- IS
- IN
- ID
- IR
- IQ
- IE
- IM
- IL
- IT
- JM
- JP
- JE
- JO
- KZ
- KE
- KI
- KP
- KR
- KW
- KG
- LA
- LV
- LB
- LS
- LR
- LY
- LI
- LT
- LU
- MO
- MG
- MW
- MY
- MV
- ML
- MT
- MH
- MQ
- MR
- MU
- YT
- MX
- FM
- MD
- MC
- MN
- ME
- MS
- MA
- MZ
- MM
- NA
- NR
- NP
- NL
- NC
- NZ
- NI
- NE
- NG
- NU
- NF
- MK
- MP
- 'NO'
- OM
- PK
- PW
- PS
- PA
- PG
- PY
- PE
- PH
- PN
- PL
- PT
- PR
- QA
- RO
- RU
- RW
- RE
- BL
- SH
- KN
- LC
- MF
- PM
- VC
- WS
- SM
- ST
- SA
- SN
- RS
- SC
- SL
- SG
- SX
- SK
- SI
- SB
- SO
- ZA
- GS
- SS
- ES
- LK
- SD
- SR
- SJ
- SE
- CH
- SY
- TW
- TJ
- TZ
- TH
- TL
- TG
- TK
- TO
- TT
- TN
- TM
- TC
- TV
- TR
- UG
- UA
- AE
- GB
- UM
- US
- UY
- UZ
- VU
- VE
- VN
- VG
- VI
- WF
- EH
- YE
- ZM
- ZW
- AX
description: Person citizenship. Send `null` or `[]` to clear.
addresses:
type: array
items:
type: object
properties:
street:
type: string
description: Address line (e.g. street, road, place).
example: Example Street
house:
type: string
description: House number or denominator.
example: 42b
postcode:
type: string
description: ZIP or postal code.
example: '12345'
city:
type: string
description: City, district, town, or village.
example: Berlin
country:
type: string
enum:
- AF
- AL
- DZ
- AS
- AD
- AO
- AI
- AQ
- AG
- AR
- AM
- AW
- AU
- AT
- AZ
- BS
- BH
- BD
- BB
- BY
- BE
- BZ
- BJ
- BM
- BT
- BO
- BQ
- BA
- BW
- BV
- BR
- IO
- BN
- BG
- BF
- BI
- CV
- KH
- CM
- CA
- KY
- CF
- TD
- CL
- CN
- CX
- CC
- CO
- KM
- CD
- CG
- CK
- CR
- HR
- CU
- CW
- CY
- CZ
- CI
- DK
- DJ
- DM
- DO
- EC
- EG
- SV
- GQ
- ER
- EE
- SZ
- ET
- FK
- FO
- FJ
- FI
- FR
- GF
- PF
- TF
- GA
- GM
- GE
- DE
- GH
- GI
- GR
- GL
- GD
- GP
- GU
- GT
- GG
- GN
- GW
- GY
- HT
- HM
- VA
- HN
- HK
- HU
- IS
- IN
- ID
- IR
- IQ
- IE
- IM
- IL
- IT
- JM
- JP
- JE
- JO
- KZ
- KE
- KI
- KP
- KR
- KW
- KG
- LA
- LV
- LB
- LS
- LR
- LY
- LI
- LT
- LU
- MO
- MG
- MW
- MY
- MV
- ML
- MT
- MH
- MQ
- MR
- MU
- YT
- MX
- FM
- MD
- MC
- MN
- ME
- MS
- MA
- MZ
- MM
- NA
- NR
- NP
- NL
- NC
- NZ
- NI
- NE
- NG
- NU
- NF
- MK
- MP
- 'NO'
- OM
- PK
- PW
- PS
- PA
- PG
- PY
- PE
- PH
- PN
- PL
- PT
- PR
- QA
- RO
- RU
- RW
- RE
- BL
- SH
- KN
- LC
- MF
- PM
- VC
- WS
- SM
- ST
- SA
- SN
- RS
- SC
- SL
- SG
- SX
- SK
- SI
- SB
- SO
- ZA
- GS
- SS
- ES
- LK
- SD
- SR
- SJ
- SE
- CH
- SY
- TW
- TJ
- TZ
- TH
- TL
- TG
- TK
- TO
- TT
- TN
- TM
- TC
- TV
- TR
- UG
- UA
- AE
- GB
- UM
- US
- UY
- UZ
- VU
- VE
- VN
- VG
- VI
- WF
- EH
- YE
- ZM
- ZW
- AX
description: Two-letter country code (ISO 3166-1 alpha-2).
additional:
type: string
nullable: true
description: >-
Additional address information (e.g. PO Box, c/o name
etc.).
example: c/o Testimonial
required:
- postcode
- city
- country
description: >-
Person's addresses. Replaces the existing set entirely. Send
`[]` to clear all stored addresses.
required:
- salutation
- first_name
- last_name
- birth_date
- email
- phone
- is_fatca
- is_pep
- tax_id
- citizenship
- addresses
additionalProperties: false
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier of a person.
salutation:
type: string
nullable: true
enum:
- MR
- MS
- OTHER
description: Person salutation.
first_name:
type: string
description: Person first name.
last_name:
type: string
description: Person last name.
birth_date:
type: number
nullable: true
description: Person date of birth.
email:
type: string
nullable: true
format: email
description: Person email.
phone:
type: string
nullable: true
description: Person phone number. (+491711010101)
example: '+491711010101'
is_fatca:
type: boolean
nullable: true
description: >-
Is the person a US taxpayer under FATCA reporting
obligations?
is_pep:
type: boolean
nullable: true
description: Is the person a Politically Exposed person (PEP)?
tax_id:
type: string
nullable: true
description: Person tax ID.
citizenship:
type: array
nullable: true
items:
type: string
enum:
- AF
- AL
- DZ
- AS
- AD
- AO
- AI
- AQ
- AG
- AR
- AM
- AW
- AU
- AT
- AZ
- BS
- BH
- BD
- BB
- BY
- BE
- BZ
- BJ
- BM
- BT
- BO
- BQ
- BA
- BW
- BV
- BR
- IO
- BN
- BG
- BF
- BI
- CV
- KH
- CM
- CA
- KY
- CF
- TD
- CL
- CN
- CX
- CC
- CO
- KM
- CD
- CG
- CK
- CR
- HR
- CU
- CW
- CY
- CZ
- CI
- DK
- DJ
- DM
- DO
- EC
- EG
- SV
- GQ
- ER
- EE
- SZ
- ET
- FK
- FO
- FJ
- FI
- FR
- GF
- PF
- TF
- GA
- GM
- GE
- DE
- GH
- GI
- GR
- GL
- GD
- GP
- GU
- GT
- GG
- GN
- GW
- GY
- HT
- HM
- VA
- HN
- HK
- HU
- IS
- IN
- ID
- IR
- IQ
- IE
- IM
- IL
- IT
- JM
- JP
- JE
- JO
- KZ
- KE
- KI
- KP
- KR
- KW
- KG
- LA
- LV
- LB
- LS
- LR
- LY
- LI
- LT
- LU
- MO
- MG
- MW
- MY
- MV
- ML
- MT
- MH
- MQ
- MR
- MU
- YT
- MX
- FM
- MD
- MC
- MN
- ME
- MS
- MA
- MZ
- MM
- NA
- NR
- NP
- NL
- NC
- NZ
- NI
- NE
- NG
- NU
- NF
- MK
- MP
- 'NO'
- OM
- PK
- PW
- PS
- PA
- PG
- PY
- PE
- PH
- PN
- PL
- PT
- PR
- QA
- RO
- RU
- RW
- RE
- BL
- SH
- KN
- LC
- MF
- PM
- VC
- WS
- SM
- ST
- SA
- SN
- RS
- SC
- SL
- SG
- SX
- SK
- SI
- SB
- SO
- ZA
- GS
- SS
- ES
- LK
- SD
- SR
- SJ
- SE
- CH
- SY
- TW
- TJ
- TZ
- TH
- TL
- TG
- TK
- TO
- TT
- TN
- TM
- TC
- TV
- TR
- UG
- UA
- AE
- GB
- UM
- US
- UY
- UZ
- VU
- VE
- VN
- VG
- VI
- WF
- EH
- YE
- ZM
- ZW
- AX
description: Person citizenship.
addresses:
type: array
nullable: true
items:
type: object
properties:
street:
type: string
description: Address line (e.g. street, road, place).
example: Example Street
house:
type: string
description: House number or denominator.
example: 42b
postcode:
type: string
description: ZIP or postal code.
example: '12345'
city:
type: string
description: City, district, town, or village.
example: Berlin
country:
type: string
enum:
- AF
- AL
- DZ
- AS
- AD
- AO
- AI
- AQ
- AG
- AR
- AM
- AW
- AU
- AT
- AZ
- BS
- BH
- BD
- BB
- BY
- BE
- BZ
- BJ
- BM
- BT
- BO
- BQ
- BA
- BW
- BV
- BR
- IO
- BN
- BG
- BF
- BI
- CV
- KH
- CM
- CA
- KY
- CF
- TD
- CL
- CN
- CX
- CC
- CO
- KM
- CD
- CG
- CK
- CR
- HR
- CU
- CW
- CY
- CZ
- CI
- DK
- DJ
- DM
- DO
- EC
- EG
- SV
- GQ
- ER
- EE
- SZ
- ET
- FK
- FO
- FJ
- FI
- FR
- GF
- PF
- TF
- GA
- GM
- GE
- DE
- GH
- GI
- GR
- GL
- GD
- GP
- GU
- GT
- GG
- GN
- GW
- GY
- HT
- HM
- VA
- HN
- HK
- HU
- IS
- IN
- ID
- IR
- IQ
- IE
- IM
- IL
- IT
- JM
- JP
- JE
- JO
- KZ
- KE
- KI
- KP
- KR
- KW
- KG
- LA
- LV
- LB
- LS
- LR
- LY
- LI
- LT
- LU
- MO
- MG
- MW
- MY
- MV
- ML
- MT
- MH
- MQ
- MR
- MU
- YT
- MX
- FM
- MD
- MC
- MN
- ME
- MS
- MA
- MZ
- MM
- NA
- NR
- NP
- NL
- NC
- NZ
- NI
- NE
- NG
- NU
- NF
- MK
- MP
- 'NO'
- OM
- PK
- PW
- PS
- PA
- PG
- PY
- PE
- PH
- PN
- PL
- PT
- PR
- QA
- RO
- RU
- RW
- RE
- BL
- SH
- KN
- LC
- MF
- PM
- VC
- WS
- SM
- ST
- SA
- SN
- RS
- SC
- SL
- SG
- SX
- SK
- SI
- SB
- SO
- ZA
- GS
- SS
- ES
- LK
- SD
- SR
- SJ
- SE
- CH
- SY
- TW
- TJ
- TZ
- TH
- TL
- TG
- TK
- TO
- TT
- TN
- TM
- TC
- TV
- TR
- UG
- UA
- AE
- GB
- UM
- US
- UY
- UZ
- VU
- VE
- VN
- VG
- VI
- WF
- EH
- YE
- ZM
- ZW
- AX
description: Two-letter country code (ISO 3166-1 alpha-2).
additional:
type: string
nullable: true
description: >-
Additional address information (e.g. PO Box, c/o
name etc.).
example: c/o Testimonial
required:
- postcode
- city
- country
description: Person's address.
required:
- external_id
- first_name
- last_name
additionalProperties: false
description: The person has been successfully updated.
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/badRequestSchema'
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unauthorizedRequestSchema'
security:
- bearerAuth: []
components:
schemas:
badRequestSchema:
type: object
properties:
code:
type: string
description: Error code
example: BAD_REQUEST
error:
type: string
description: Error message for debugging purposes
example: Request validation failed. 1 issue found.
issues:
type: array
items:
type: object
properties:
code:
type: string
description: Issue code
example: INVALID_TYPE
path:
type: string
description: Issue path starting with body, params, querystring, or headers
example: body.registered_at
message:
type: string
description: Issue message for debugging purposes
example: Invalid type
required:
- code
- path
- message
description: List of issues
example:
- code: INVALID_TYPE
path: body.registered_at
message: Invalid type
required:
- code
- error
- issues
description: Bad Request, see error message for details.
example:
code: BAD_REQUEST
error: Request validation failed. 1 issue found.
issues:
- code: INVALID_TYPE
path: body.registered_at
message: Invalid type
unauthorizedRequestSchema:
type: object
properties:
error:
type: string
description: Error details.
example: Unauthorized
code:
type: string
description: Error code.
example: UNAUTHORIZED
required:
- error
- code
description: Unauthorized Request.
example:
error: Unauthorized
code: UNAUTHORIZED
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Your Tilta API key, sent as `Bearer `.
````