Create or upsert a party by external_id

POST

/api/public/v1/parties

Code sample: cURL

curl --request POST \
  --url 'https://api.getzutax.com/api/public/v1/parties' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <unique-request-key>' \
  --data '{
  "external_id": "cust-obs-001",
  "legal_name": "Optimum Business Solution Ltd",
  "trading_name": "OBS",
  "party_type": "customer",
  "tax_id": "TIN-12345678",
  "registration_number": "RC-900123",
  "email": "accounts@obs.ng",
  "phone": "+2348012345678",
  "website": "https://obs.ng",
  "business_description": "ERP and accounting integration services",
  "is_peppol_participant": true,
  "addresses": [
    {
      "address_type": "postal",
      "street_name": "Adeola Odeku Street",
      "building_number": "12",
      "city_name": "Lagos",
      "postal_zone": "101241",
      "state": "Lagos",
      "country_code": "NG",
      "is_primary": true
    }
  ],
  "identifiers": [
    {
      "scheme_id": "NG:TIN",
      "identifier": "12345678-0001",
      "is_primary": true
    }
  ]
}'

• Production API
• Staging API

Authorizations

• HTTPBearer

Request Body ^required

Media type application/json

PartyCreateInput

object

external_id

required

External Id

string

>= 1 characters <= 255 characters

legal_name

required

Legal Name

string

>= 1 characters <= 500 characters

trading_name

Any of:

string

string

null

null

party_type

Party Type

string

default: customer

Allowed values: supplier customer both

tax_id

Any of:

string

string

<= 100 characters

null

null

registration_number

Any of:

string

string

null

null

email

Any of:

string

string

null

null

phone

Any of:

string

string

null

null

website

Any of:

string

string

null

null

business_description

Any of:

string

string

null

null

is_peppol_participant

Is Peppol Participant

boolean

addresses

Addresses

Array<object>

PartyAddressInput

object

address_type

Address Type

string

default: postal

street_name

Any of:

string

string

null

null

additional_street_name

Any of:

string

string

null

null

building_number

Any of:

string

string

null

null

city_name

required

City Name

string

<= 100 characters

postal_zone

Any of:

string

string

null

null

state

Any of:

string

string

null

null

lga

Any of:

string

string

null

null

country_code

required

Country Code

string

>= 2 characters <= 2 characters

is_primary

Is Primary

boolean

identifiers

Identifiers

Array<object>

PartyIdentifierInput

object

scheme_id

required

Scheme Id

string

>= 1 characters <= 10 characters

identifier

required

Identifier

string

>= 1 characters <= 200 characters

is_primary

Is Primary

boolean

Examples

Example Customer party

Create or update a customer from an ERP

{
  "external_id": "cust-obs-001",
  "legal_name": "Optimum Business Solution Ltd",
  "trading_name": "OBS",
  "party_type": "customer",
  "tax_id": "TIN-12345678",
  "registration_number": "RC-900123",
  "email": "accounts@obs.ng",
  "phone": "+2348012345678",
  "website": "https://obs.ng",
  "business_description": "ERP and accounting integration services",
  "is_peppol_participant": true,
  "addresses": [
    {
      "address_type": "postal",
      "street_name": "Adeola Odeku Street",
      "building_number": "12",
      "city_name": "Lagos",
      "postal_zone": "101241",
      "state": "Lagos",
      "country_code": "NG",
      "is_primary": true
    }
  ],
  "identifiers": [
    {
      "scheme_id": "NG:TIN",
      "identifier": "12345678-0001",
      "is_primary": true
    }
  ]
}

Responses

200

Successful Response

Media type application/json

PartyResponse

object

id

required

Id

string format: uuid

external_id

required

Any of:

string

string

null

null

legal_name

required

Legal Name

string

trading_name

Any of:

string

string

null

null

party_type

required

Party Type

string

Allowed values: supplier customer both

tax_id

Any of:

string

string

null

null

is_active

required

Is Active

boolean

is_peppol_participant

Is Peppol Participant

boolean

Examples

Example Party upserted

Existing party updated

{
  "id": "8a1c7f6c-61a1-4d89-8d96-3f7e7747f0c0",
  "external_id": "cust-obs-001",
  "legal_name": "Optimum Business Solution Ltd",
  "trading_name": "OBS",
  "party_type": "customer",
  "tax_id": "TIN-12345678",
  "is_active": true,
  "is_peppol_participant": true
}

422

Validation Error

Media type application/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

Examples

Example Sample response

422 response example

{
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string"
    }
  ]
}