API Docs

The Customer party object

When you create a sales invoice, sales credit note, or proforma invoice, you pass the buyer's details inline in the accounting_customer_party object. This page documents validation rules for document create payloads — not a standalone customer profile API.

On sales documents, the supplier (accounting_supplier_party) is set automatically from the {profileId} business profile—do not send it. On purchase documents, the customer (accounting_customer_party) is set from the profile—see Supplier validation for the party you must send.

Customer rules are not the same as business profile or supplier rules.

Before you start

Decide whether the customer is a business or an individual. On sale documents, Marmin infers this from scheme_agency_id: EID or PAS means individual; all other values (or omission) mean business.
Check whether the customer's address is in the UAE (country_code = AE) or outside the UAE.
Registration details are optional. You do not need to send scheme_agency_id, company_id, authority_name, or passport_issuing_country_code unless you want to include them.
Keep registration and VAT separate:
Registration number (company_id) — trade license, cabinet decision, Emirates ID, passport number, or other identifier (only when you send registration details)
VAT number / TRN (party_tax_scheme.company_id) — 15-digit UAE tax registration number

Request fields

Fields on accounting_customer_party when creating or resubmitting sale documents. Rows are ordered Required → Conditional → Optional.

Field	Type	Required	Description	Validation
`name`	string	Required	Display name for the customer.	Non-empty text.
`email`	string	Required	Customer email address.	Valid email format.
`postal_address`	object	Required	Customer address.	See Request postal_address section for details.
`party_name`	string	Conditional	Legal name of the business.	Required for business customers. Do not send for individuals.
`company_id`	string	Conditional	Official registration or identity number. Not the VAT/TRN.	Required when `scheme_agency_id` is provided.
`authority_name`	string	Optional	Issuing authority for the trade license.	Optional. Required only when `scheme_agency_id` is `TL` and registration details are included.
`passport_issuing_country_code`	string	Conditional	Country that issued the passport.	Required when `scheme_agency_id` is `PAS` and registration details are included.
`tin`	string	Conditional	Taxpayer Identification Number (TIN) from EmaraTax.	Required for UAE business customers — 10 characters, starts with `1`. Do not send for non-UAE business customers or individuals.
`endpoint_id`	string	Required	Peppol electronic address (participant identification).	Required on every document. Use the buyer's 10-digit TIN when the buyer is UAE e-invoicing compliant and Peppol-registered. For deemed supply, exports, or non-compliant buyers, use the Endpoint identification table. Must not be blank.
`endpoint_scheme_id`	string	Required	Peppol endpoint scheme (participant scheme ID).	Required on every document. Typically `0235` for UAE. See Endpoint identification and Get Electronic Address Schemes section for details.
`party_name_in_local_language`	string	Optional	Customer name in Arabic or local language.
`scheme_agency_id`	string	Optional	Registration type when including registration details.	See Get Registration Types section for details.
`party_tax_scheme`	object	Optional	UAE VAT details for UAE business customers.	If either field is sent, both are required. See Request party_tax_scheme section for details. Do not send if the customer is not eligible for VAT, or for non-UAE business customers or individuals.
`telephone`	string	Optional	Customer telephone number.

Do not send on create: profile_id (use only when referencing an existing registered profile; returned in responses). Do not confuse with business_profile_id in the URL path.

Request postal_address

Field	Type	Required	Description	Validation
`street_name`	string	Required	Street name or primary address line.	Non-empty.
`city_name`	string	Required	City or town.	Non-empty.
`country_subentity`	string	Required	Emirate, state, or region code (e.g. `DXB`).	For UAE (`AE`), use Get UAE Subdivisions.
`country`	string	Required	Country name (e.g. `United Arab Emirates`).	Non-empty.
`country_code`	string	Required	ISO 3166-1 alpha-2 country code (e.g. `AE`).	See Get Countries section for details.
`additional_street_name`	string	Optional	Additional street details.
`postal_zone`	string	Optional	Postal or ZIP code.
`address_line`	string	Optional	Additional address line.

Request party_tax_scheme

Field	Type	Required	Description	Validation
`company_id`	string	Conditional	UAE VAT registration number (TRN).	15 digits; starts with `1` and ends with `03`. Required if `party_tax_scheme` is sent.
`tax_scheme`	string	Conditional	Tax scheme, usually `VAT`.	Required if `party_tax_scheme` is sent. See Get Tax Schemes section for details.

Endpoint identification

endpoint_id and endpoint_scheme_id are required on accounting_customer_party for every sale document, credit note, and proforma invoice. Marmin no longer defaults the buyer endpoint when either field is omitted — you must set the correct values explicitly.

UAE e-invoicing compliant buyer (Peppol-registered): use the buyer's 10-digit TIN as endpoint_id with endpoint_scheme_id 0235.

Special scenarios: use the FTA substitute participant identification from the table below.

No.	Transaction type	Participant scheme ID (`endpoint_scheme_id`)	Participant identification (`endpoint_id`)
1	Invoice transaction type code is (X1XXXXXX) Deemed supply	`0235`	`9900000097`
2	Invoice transaction type code is (XXXXXXX1) Exports (receiver not registered in Peppol)	`0235`	`9900000099`
3	Buyer is not subject to UAE e-invoicing regulations	`0235`	`9900000098`

Use row 3 when the buyer has not implemented e-invoicing or does not have a Peppol endpoint. Previously Marmin applied 9900000098 automatically when the endpoint was omitted — that default no longer applies.

Response fields

Fields returned on accounting_customer_party in document retrieve/list/create responses.

Core fields

Field	Type	Source	Description
`name`	string	User Provided	Display name echoed from the request.
`email`	string	User Provided	Customer email echoed from the request.
`party_name`	string	User Provided	Legal business name when provided on create.
`party_name_in_local_language`	string	User Provided	Local-language name when provided.
`scheme_agency_id`	string	User Provided	Registration type when provided.
`company_id`	string	User Provided	Registration number when provided.
`authority_name`	string	User Provided	Trade license authority when provided.
`passport_issuing_country_code`	string	User Provided	Passport country when provided.
`tin`	string	User Provided	TIN when provided.
`party_tax_scheme`	object	User Provided	VAT details when provided on create.
`endpoint_id`	string	User Provided	Peppol endpoint when provided.
`endpoint_scheme_id`	string	User Provided	Endpoint scheme when provided.
`telephone`	string	User Provided	Telephone when provided.
`profile_id`	string	System Provided	Business profile identifier when the party was linked to a registered profile. Do not send on create — returned in responses only.
`postal_address`	object	User Provided	Address with optional system fields. See Response postal_address section for details.

Response postal_address

Field	Type	Source	Description
`id`	string (UUID)	System Provided	Persisted address record identifier.
`street_name`	string	User Provided	Street name from request.
`additional_street_name`	string	User Provided	Additional street details.
`city_name`	string	User Provided	City name.
`postal_zone`	string	User Provided	Postal code.
`country_subentity`	string	User Provided	Region or emirate code.
`address_line`	string	User Provided	Additional address line.
`country`	string	User Provided	Country name.
`country_code`	string	User Provided	ISO country code.

Conditional field rules

Condition	Affected fields	Rule
Business customer (not `EID`/`PAS`)	`party_name`	Required.
Individual customer (`scheme_agency_id` is `EID` or `PAS`)	`party_name`, `tin`, `party_tax_scheme`	Do not send.
UAE business customer	`tin`	Required — 10 characters, starts with `1`.
Non-UAE business customer	`tin`, `party_tax_scheme`	Do not send.
`scheme_agency_id` is provided	`company_id`	Required.
`scheme_agency_id` is `TL`	`authority_name`	Required.
`scheme_agency_id` is `PAS`	`passport_issuing_country_code`	Required when registration details are included.
`party_tax_scheme` partially sent	`company_id`, `tax_scheme`	Both required with valid TRN format.
Export transaction (`profile_execution_id` position 8 is `1`, format `XXXXXXX1`)	`party_tax_scheme` on non-UAE buyer	Optional — VAT may be omitted.
Non-UAE B2B (not export)	`party_tax_scheme`	Forbidden.
Deemed supply (`profile_execution_id` position 2 is `1`, format `X1XXXXXX`)	`endpoint_id`, `endpoint_scheme_id`	Required — use `9900000097` and `0235`. See Endpoint identification.
Export transaction (`profile_execution_id` position 8 is `1`, format `XXXXXXX1`) and receiver not registered in Peppol	`endpoint_id`, `endpoint_scheme_id`	Required — use `9900000099` and `0235`. See Endpoint identification.
Buyer not subject to UAE e-invoicing regulations	`endpoint_id`, `endpoint_scheme_id`	Required — use `9900000098` and `0235`. See Endpoint identification.
UAE e-invoicing compliant buyer (Peppol-registered)	`endpoint_id`, `endpoint_scheme_id`	Required — use buyer 10-digit TIN and `0235`.

Validation by scenario

UAE business customer

What to send	Rule
`name`, `email`, `postal_address`	Required
`party_name`	Required
`tin`	Required — 10 characters, starts with `1`
`scheme_agency_id`, `company_id`, `authority_name`	Optional — registration details are not required
`party_tax_scheme`	Optional; if sent, both TRN and `tax_scheme` required with valid TRN format
`passport_issuing_country_code`	Do not send

Non-UAE business customer

What to send	Rule
`name`, `email`, `party_name`, `postal_address`	Required
`scheme_agency_id`	Optional; `OTH` is typical
`company_id`	Optional; only send with `scheme_agency_id`
`tin`	Do not send
`party_tax_scheme`	Do not send

UAE individual customer

What to send	Rule
`name`, `email`, `postal_address`	Required
`scheme_agency_id`	Optional; if sent, must be `EID` or `PAS`
`party_name`	Do not send
`authority_name`	Do not send
`tin`, `party_tax_scheme`	Do not send
`passport_issuing_country_code`	Required when `scheme_agency_id` is `PAS`

If you include registration details

Registration fields are optional. If you choose to send scheme_agency_id, the following rules apply:

Registration type (`scheme_agency_id`)	Additional fields when registration is included
Any	`company_id` is required when `scheme_agency_id` is provided
`TL` (Trade License)	`authority_name` is also required
`PAS` (Passport)	`passport_issuing_country_code` is also required for UAE addresses
Business customer (UAE)	`TL` or `CD` are typical
Business customer (non-UAE)	`OTH` is typical
Individual customer	`EID` or `PAS`

See Get Registration Types section for details.

Using this object on sale documents

Include these fields on accounting_customer_party when you create or resubmit a sales invoice or sales credit note. The same rules apply on proforma invoices for the customer party.

For export transactions, see Export transaction with delivery.