API Docs

The Supplier party object

When you create a purchase invoice or purchase credit note, you pass the seller's details inline in the accounting_supplier_party object. This page documents validation rules for document create payloads — not a standalone supplier profile API.

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

Before you start

Check whether the supplier'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, or authority_name unless you want to include them.
Keep registration and VAT separate:
Registration number (company_id) — trade license or cabinet decision number (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_supplier_party when creating or resubmitting purchase documents. Rows are ordered Required → Conditional → Optional.

Field	Type	Required	Description	Validation
`name`	string	Required	Display name for the supplier.	Non-empty text.
`party_name`	string	Required	Legal name of the supplier business.	Non-empty text.
`email`	string	Required	Supplier email address.	Valid email format.
`postal_address`	object	Required	Supplier address.	See Request postal_address section for details.
`telephone`	string	Conditional	Supplier telephone number.	Required when `postal_address.country_code` is `AE`.
`company_id`	string	Conditional	Official registration 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.
`tin`	string	Conditional	Taxpayer Identification Number (TIN) from EmaraTax.	Required for UAE suppliers — 10 characters, starts with `1`. Do not send for non-UAE suppliers.
`endpoint_id`	string	Required	Peppol electronic address (participant identification).	Required on every document. Use the supplier's 10-digit TIN when the supplier is UAE e-invoicing compliant and Peppol-registered. For deemed supply, exports, or non-compliant suppliers, 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	Supplier name in Arabic or local language.
`logo_url`	string	Optional	URL to the supplier's logo image.	Valid URL when sent.
`scheme_agency_id`	string	Optional	Registration type when including registration details.	`TL` or `CD` typical for UAE. See Get Registration Types section for details.
`party_tax_scheme`	object	Optional	UAE VAT details for UAE suppliers.	If either field is sent, both are required. See Request party_tax_scheme section for details. Do not send for non-UAE suppliers.

Do not send on create: profile_id (returned in responses when linked to a registered profile).

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_supplier_party for every purchase document and credit note. Marmin no longer defaults the supplier endpoint when either field is omitted — you must set the correct values explicitly.

UAE e-invoicing compliant supplier (Peppol-registered): use the supplier'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	Supplier is not subject to UAE e-invoicing regulations	`0235`	`9900000098`

Use row 3 when the supplier 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_supplier_party in document responses.

Core fields

Field	Type	Source	Description
`name`	string	User Provided	Display name echoed from the request.
`party_name`	string	User Provided	Legal name echoed from the request.
`party_name_in_local_language`	string	User Provided	Local-language name when provided.
`email`	string	User Provided	Email echoed from the request.
`telephone`	string	User Provided	Telephone when provided.
`logo_url`	string	User Provided	Logo URL 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.
`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.
`profile_id`	string	System Provided	Business profile identifier when linked. Do not send on create.
`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
UAE supplier (`postal_address.country_code` = `AE`)	`telephone`, `tin`	Both required. `tin` — 10 characters, starts with `1`.
Non-UAE supplier	`tin`, `party_tax_scheme`	Do not send.
`scheme_agency_id` is provided	`company_id`	Required.
`scheme_agency_id` is `TL`	`authority_name`	Required.
`party_tax_scheme` partially sent	`company_id`, `tax_scheme`	Both required with valid TRN format.
Disclosed agent billing (`profile_execution_id` sixth character is `1`)	`seller_supplier_party.id` on sale invoices	Separate field — Principle TRN; see Disclosed agent billing.
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.
Supplier not subject to UAE e-invoicing regulations	`endpoint_id`, `endpoint_scheme_id`	Required — use `9900000098` and `0235`. See Endpoint identification.
UAE e-invoicing compliant supplier (Peppol-registered)	`endpoint_id`, `endpoint_scheme_id`	Required — use supplier 10-digit TIN and `0235`.

Validation by scenario

UAE supplier

What to send	Rule
`name`, `party_name`, `email`, `postal_address`	Required
`telephone`	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 supplier

What to send	Rule
`name`, `party_name`, `email`, `postal_address`	Required
`tin`	Do not send
`party_tax_scheme`	Do not send
Registration fields	Optional

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
UAE supplier	`TL` or `CD` are typical

See Get Registration Types section for details.

Using this object on purchase documents

Include these fields on accounting_supplier_party when you create or resubmit a purchase invoice or purchase credit note.