Vendor related parties

Related parties are the people linked to a legal entity vendor: partners, administrators, directors, attorneys-in-fact and the parent company. An individual vendor has no related parties (400, VRG000054).

To submit the analysis, a legal entity vendor needs:

• at least one non-inactive related party (pending_registry or active);
• at least one party with is_representative: true;
• an identification document for each representative;
• a power of attorney (power_of_attorney) for each attorney-in-fact (attorney).

See Documents.

Declare the parties while the analysis is being filled in

While an analysis is in progress, a party can only be created, updated, activated or deactivated in pending_submission. A party created when the vendor has no analysis in progress is not automatically included in the next analysis: open the new analysis first and declare the parties afterwards. If the party was created earlier, it joins the analysis in pending_submission when you update its data.

Lifecycle

Status	Description
pending_registry	Declared, waiting for the analysis approval. It is also the status of a reactivated party.
active	Confirmed on analysis approval.
inactive	Deactivated by the manager; discarded on the approval of an analysis that did not include it; or still in pending_registry when the analysis was rejected.

Related party types

related_party_type	Description
partner	Partner
administrator	Administrator
director	Director
president	President
manager	Manager
attorney	Attorney-in-fact. Requires its own power_of_attorney document.
parent_company	Parent company. The only legal entity type (CNPJ); cannot be a representative.

is_representative is independent of the type: it marks who legally represents the vendor and signs on its behalf.

Declare a related party

Available on

Profile	Host	Required permission
Manager	manager-api	Write
Consultant	consultant-api	Active integration

Base URL for each host: Environments (Hosts).

ENDPOINT

/vendor_registry/vendor/{vendor_key}/related_party

METHOD

POST

Path parameters

Parameter	Type	Description
vendor_key	string	Vendor key (UUID).

Request body

{
    "name": "João da Silva",
    "related_party_type": "administrator",
    "document_number": "123.456.789-09",
    "email": "joao.silva@auditoresexemplo.com.br",
    "nationality": "BRA",
    "ownership_percentage": 50.0,
    "is_representative": true
}

Body attributes

Field	Type	Required	Description
name	string	Yes	Name, from 1 to 255 characters.
related_party_type	string	Yes	Party type. See types.
document_number	string	Conditional	CPF (CNPJ for parent_company), with or without punctuation, from 11 to 18 characters. Required when nationality is BRA, when is_representative is true or when the type is attorney. Only validated as a CPF (or CNPJ) when nationality is BRA. Cannot be changed later.
nationality	string	No	Country as an ISO 3166-1 alpha-3 code. Default: BRA.
passport_number	string	No	Passport, from 1 to 18 characters. Identifies a foreign party without a CPF. Cannot be changed once stored.
email	string	Conditional	Email, maximum of 255 characters. Required when is_representative is true.
ownership_percentage	number	No	Ownership interest, from 0 to 100, stored with two decimal places.
is_representative	boolean	No	Legal representative of the vendor. Default: false. parent_company cannot be a representative.

A foreign party is identified by document_number or by passport_number; at least one of the two is required. If an inactive party with the same CPF (or passport) already exists, it is reactivated under the same related_party_key with the new data.

Response

STATUS

201

Response body

{
    "related_party_key": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "João da Silva",
    "document_number": "123.456.789-09",
    "email": "joao.silva@auditoresexemplo.com.br",
    "related_party_type": "administrator",
    "is_representative": true,
    "ownership_percentage": 50.0,
    "nationality": "BRA",
    "passport_number": null,
    "status": "pending_registry"
}

Response attributes

Field	Type	Description
related_party_key	string	Related party key (UUID). Use it for the party's documents and for updates.
name	string	Name.
document_number	string	CPF or CNPJ with punctuation, or null for a foreign party identified only by passport.
email	string	Email, or null.
related_party_type	string	Party type.
is_representative	boolean	Legal representative.
ownership_percentage	number	Ownership interest, or null.
nationality	string	ISO 3166-1 alpha-3 country.
passport_number	string	Passport, or null.
status	string	pending_registry, active or inactive.

Update related party data

Changes only the fields sent; the others stay as they are. Requires an analysis in progress, in pending_submission. document_number cannot be sent or changed.

Available on

Profile	Host	Required permission
Manager	manager-api	Write
Consultant	consultant-api	Active integration

Base URL for each host: Environments (Hosts).

ENDPOINT

/vendor_registry/vendor/{vendor_key}/related_party/{related_party_key}/data

METHOD

PUT

Request body

{
    "email": "joao.silva@auditoresexemplo.com.br",
    "ownership_percentage": 60.0
}

Accepted fields, all optional and with the same rules as creation: name, related_party_type, nationality, passport_number (only if not stored yet), email, ownership_percentage, is_representative.

Response

STATUS

200

The updated related party, with the same structure as on creation.

Activate or deactivate a related party

Deactivates a party that has left the vendor's structure, or includes a deactivated party again. If there is an analysis in progress, it must be in pending_submission.

Available on

Profile	Host	Required permission
Manager	manager-api	Write
Consultant	consultant-api	Active integration

Base URL for each host: Environments (Hosts).

ENDPOINT

/vendor_registry/vendor/{vendor_key}/related_party/{related_party_key}

METHOD

PUT

Request body

{
    "status": "inactive"
}

Field	Type	Required	Description
status	string	Yes	inactive or active. See the rules below.

• inactive deactivates the party.
• active adds an inactive party back to the analysis being filled in. It returns as pending_registry and only becomes active on approval.
• Reactivation is refused if the vendor already has another active or pending_registry party with the same document or passport (400, VRG000052).
• active sent for a party that is already active or pending_registry changes nothing: the response returns the party as it is.

Response

STATUS

200

The related party, with the same structure as on creation. status comes as inactive or pending_registry, or unchanged when active was sent for a party that was not inactive.

Errors

STATUS

409

Registration already submitted for analysis

There is an analysis in progress outside pending_submission. When updating data, the error also occurs when the vendor has no analysis in progress.

{
  "title": "Vendor Registration Already Submitted",
  "description": "The current analysis of the vendor 5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57 is no longer pending submission, so the registration cannot be edited.",
  "translation": "Cadastro ja enviado para analise.",
  "code": "VRG000072"
}

STATUS

400

code	When it happens
VRG000054	The vendor is an individual and cannot have related parties.
VRG000002	With nationality BRA, document_number is not a valid CPF (or a valid CNPJ, for parent_company).
VRG000084	nationality is not an ISO 3166-1 alpha-3 code.
VRG000085	BRA party without document_number, or foreign party without document_number and without passport_number.
VRG000086	Foreign party without document_number marked as a representative or of type attorney.
VRG000087	parent_company with is_representative: true.
VRG000052	An active or pending_registry party with that document (or, without a document, with that passport) already exists for this vendor. Also applies when reactivating an inactive party.
VRG000055	Representative without email.
VRG000092	You tried to change a passport_number that is already stored.

Example

{
  "title": "Related Party Email Required",
  "description": "A related party of type administrator must declare an email.",
  "translation": "Uma parte relacionada do tipo administrator precisa declarar um e-mail.",
  "code": "VRG000055"
}

STATUS

404

code	When it happens
VRG000014	The vendor_key does not exist or the vendor is not visible to you.
VRG000053	The related_party_key does not belong to this vendor.

Authentication, permission and host errors: see API Errors.

Next step

Documents: upload the articles of association and the identification of each representative.