> For the complete documentation index, see [llms.txt](https://detected.gitbook.io/detected-api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://detected.gitbook.io/detected-api-docs/api-reference/representatives.md).

# Representatives

Representatives are the people or entities associated with a profile, for example company directors, ultimate beneficial owners (UBOs), trustees, individuals, shareholder entities and director companies. A profile can have multiple representatives.

## List representatives

> Returns a list of representatives for your account. A representative can be a natural person or a legal entity, and may or may not be linked to a profile. The list includes representatives added through the portal or case management, and those converted from external data sources. Use the query parameters to filter the results.\
> \
> The representative types are: \`director\`, \`identity\`, \`ownership\`, \`declaratory\`, \`principal\`, \`director\_company\`, \`treasurer\`, \`secretary\`, \`syndicator\`, \`member\`, \`agent\`, \`designated\_member\`, \`club\_manager\`, \`authorised\_representative\`, \`authorised\_signatory\`, \`trustee\_company\`, \`trustee\`, \`partner\_company\`, \`partner\`, \`syndicate\_manager\`, \`individual\`, \`lead\_partner\`, \`shareholder\`, \`shareholder\_company\`, \`shareholder\_entity\`.

```json
{"openapi":"3.0.0","info":{"title":"Detected API","version":"v2"},"tags":[{"name":"Representatives","description":"Representatives are the people or entities associated with a profile, for example company directors, ultimate beneficial owners (UBOs), trustees, individuals, shareholder entities and director companies. A profile can have multiple representatives."}],"servers":[{"url":"https://api.detected.app/api/v2/public","description":"Production"}],"security":[{"AccessToken":[]}],"components":{"securitySchemes":{"AccessToken":{"type":"http","description":"The API uses OAuth 2.0. Request an access token with **Create an access token** (`POST /oauth/token`), sending the client ID and client secret of your integration client, and your account slug. Send the access token in the `Authorization` header of every request, in the format `Authorization: Bearer <access_token>`. The access token carries the scopes set on your integration client in the dashboard. Access tokens expire. When one expires, request a new one.","bearerFormat":"OAuth 2.0 access token","scheme":"bearer"}},"parameters":{"order_by":{"name":"order_by","in":"query","description":"Direction to sort the results in: `asc` for ascending or `desc` for descending. Use it together with `sort_by`; it has no effect if `sort_by` is omitted. The default is `asc`.","schema":{"type":"string","enum":["desc","asc"]}},"page":{"name":"page","in":"query","description":"Page number of the results to return, starting from 1. The number of items per page is returned in `meta.per_page`.","schema":{"type":"integer","minimum":1}}},"headers":{"X-RateLimit-Limit":{"description":"Maximum number of requests allowed in the rate limit window.","schema":{"type":"number","nullable":false}},"X-RateLimit-Remaining":{"description":"Number of requests remaining in the current rate limit window.","schema":{"type":"number","nullable":false}},"Retry-After":{"description":"Number of seconds to wait before making another request. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}},"X-RateLimit-Reset":{"description":"Unix timestamp (in seconds) at which the rate limit resets. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}}},"schemas":{"RepresentativesResource":{"title":"Representative Resource","required":["id","profile_id","customer_reference","is_company","types"],"properties":{"id":{"description":"Representative UUID.","type":"string","nullable":false},"profile_id":{"description":"UUID of the profile the representative is linked to.","type":"string","format":"uuid","nullable":false},"customer_reference":{"description":"The customer reference of the profile the representative belongs to, as set when the profile was created.","type":"string","nullable":false},"is_company":{"description":"Whether the representative is a legal entity (`true`) or a natural person (`false`).","type":"boolean","nullable":false},"is_linked":{"description":"Whether the representative is linked to another representative record, either as the master or as a child of a link.","type":"boolean","nullable":false},"is_master_link":{"description":"Whether the representative is the master record of a representative link, i.e. other representative records are linked to it.","type":"boolean","nullable":false},"is_child_link":{"description":"Whether the representative is linked to a master representative record.","type":"boolean","nullable":false},"review_status":{"description":"Review status of the representative.","properties":{"status":{"description":"Current review status.","type":"string","enum":["pending","needs_review","verified","rejected","fraud","additional_information","previously_verified"],"nullable":false},"verified_at":{"description":"Date and time the representative was verified, or `null` if they have not been verified.","type":"string","nullable":true},"updated_at":{"description":"Date and time the review status was last updated.","type":"string","nullable":false},"created_at":{"description":"Date and time the review status was created.","type":"string","nullable":false}},"type":"object","nullable":true},"types":{"description":"Types assigned to the representative.","type":"array","items":{"type":"string","enum":["director","identity","ownership","declaratory","principal","director_company","treasurer","secretary","syndicator","member","agent","designated_member","club_manager","authorised_representative","authorised_signatory","trustee_company","trustee","partner_company","partner","syndicate_manager","individual","lead_partner","shareholder","shareholder_company","shareholder_entity"]},"nullable":false},"role_type":{"description":"Role types assigned to the representative: `Director`, `Designated Member`, `Partner`, `Company Principal` or `Other`.","type":"array","items":{"type":"string"},"nullable":true},"full_name":{"description":"Full name of the representative, or the company/legal entity name.","type":"string","nullable":true},"title":{"description":"Title of the representative, for example `Mr` or `Dr`.","type":"string","nullable":true},"professional_profile":{"description":"URL of the representative's professional profile.","type":"string","nullable":true},"country":{"description":"Name of the country of the address.","type":"string","nullable":true},"country_code":{"description":"Country of the address, ISO 3166-1 alpha-2 country code.","type":"string","nullable":true},"country_of_residence":{"description":"Name of the country of residence.","type":"string","nullable":true},"residence_country_code":{"description":"Country of residence, ISO 3166-1 alpha-2 country code.","type":"string","nullable":true},"personal_number":{"description":"Personal phone number.","type":"string","nullable":true},"first_name":{"description":"First name.","type":"string","nullable":true},"middle_name":{"description":"Middle name.","type":"string","nullable":true},"last_name":{"description":"Last name.","type":"string","nullable":true},"dob":{"description":"Date of birth, in `YYYY-MM-DD` format.","type":"string","nullable":true},"email":{"description":"Email address of the representative.","type":"string","nullable":true},"job_title":{"description":"Job title.","type":"string","nullable":true},"social_security_number":{"description":"US Social Security number of the representative, in the format `XXX-XX-XXXX`.","type":"string","nullable":true},"social_security_number_last_4":{"description":"Last 4 digits of the representative's US Social Security number.","type":"string","nullable":true},"passport_number":{"description":"Passport number.","type":"string","nullable":true},"landline_number":{"description":"Landline phone number.","type":"string","nullable":true},"apartment_number":{"description":"Apartment number.","type":"string","nullable":true},"address_1":{"description":"First line of the address.","type":"string","nullable":true},"address_2":{"description":"Second line of the address.","type":"string","nullable":true},"city":{"description":"City.","type":"string","nullable":true},"state":{"description":"State or region.","type":"string","nullable":true},"post_code":{"description":"Postcode.","type":"string","nullable":true},"country_of_birth":{"description":"Name of the country of birth.","type":"string","nullable":true},"birth_country_code":{"description":"Country of birth, ISO 3166-1 alpha-2 country code.","type":"string","nullable":true},"share_percentage":{"description":"Percentage of shares held by the representative.","type":"number","nullable":true},"shareholder_type":{"description":"Type of shareholding. `Direct` or `Indirect` for representatives created through the API; representatives imported from a data source may carry provider-specific values.","type":"string","nullable":true},"nationality":{"description":"Nationality.","type":"string","nullable":true},"nationality_code":{"description":"Nationality, ISO 3166-1 alpha-2 country code.","type":"string","nullable":true},"person_type_details":{"description":"Extra details that depend on the representative's type, such as the appointment date or ownership percentage. The fields returned depend on the representative's types (for example ownership percentages for owners, or company details for company representatives), and other fields may be returned.","properties":{"appointment_date":{"description":"Date the representative was appointed.","type":"string","nullable":true},"majority":{"description":"Whether the representative's ownership meets the majority threshold given in `majority_percentage`.","type":"boolean","nullable":true},"governing":{"description":"Whether the representative has a governing role.","type":"boolean","nullable":true},"responsibility":{"description":"Whether the representative has significant responsibility.","type":"boolean","nullable":true},"majority_percentage":{"description":"The majority ownership threshold percentage, taken from the portal configuration.","type":"string","nullable":true},"specific_ownership_percentage":{"description":"Percentage of the company owned by the representative.","type":"string","nullable":true},"direct_ownership_percentage":{"description":"Direct ownership percentage, or `null` if not available."},"indirect_ownership_percentage":{"description":"Indirect ownership percentage, or `null` if not available."},"beneficial_ownership_percentage":{"description":"Beneficial ownership percentage, or `null` if not available."},"implied_direct_ownership_percentage":{"description":"Implied direct ownership percentage, calculated through the ownership structure, or `null` if not available."},"implied_indirect_ownership_percentage":{"description":"Implied indirect ownership percentage, calculated through the ownership structure, or `null` if not available."},"implied_beneficial_ownership_percentage":{"description":"Implied beneficial ownership percentage, calculated through the ownership structure, or `null` if not available."},"degree_of_separation":{"description":"How many levels of ownership separate the representative from the profile's entity, or `null` if not available."},"company_name":{"description":"For company representatives, the company name.","type":"string"},"company_number":{"description":"For company representatives, the company registration number.","type":"string"},"full_address":{"description":"For company representatives, the registered address.","type":"string"},"trading_address":{"description":"For company representatives, the trading address.","type":"object","additionalProperties":true},"named_representative":{"description":"For company representatives, the named individual representing the company, or `null`.","type":"string","nullable":true},"is_active":{"description":"Whether the representative is currently active in the role, or `null` if not known."},"position_type":{"description":"Type of position held, or `null` if not known."},"resignation_date":{"description":"Date the representative resigned from the role, or `null` if they haven't."}},"type":"object","nullable":true,"additionalProperties":true},"copy_address":{"description":"Whether the trading address is the same as the registered address. Only set for `director_company` representatives.","type":"boolean","nullable":true},"updated_at":{"description":"Date and time the representative was last updated.","type":"string","nullable":true},"created_at":{"description":"Date and time the representative was created.","type":"string","nullable":true},"screenings":{"description":"AML screening results for the representative. Only returned by **Retrieve a representative** (`GET /representatives/{uuid}`); `null` if no screening has been run.","properties":{"details":{"description":"Details of the screening search that was performed.","properties":{"provider":{"description":"Screening provider the search was performed with.","type":"string","enum":["ion_group","comply_advantage","lseg_zfs"],"nullable":false},"performed_at":{"description":"Date the screening was performed.","type":"string","nullable":false},"search_term":{"description":"Term the representative was searched with against the provider.","type":"string","nullable":false},"search_payload":{"description":"The search sent to the screening provider. Its structure is provider-specific."},"is_monitored":{"description":"Whether the representative is enrolled in ongoing monitoring with the provider.","type":"boolean","nullable":false}},"type":"object","nullable":false},"screenings":{"description":"List of screening matches returned by the provider.","type":"array","items":{"type":"object","additionalProperties":true,"description":"One screening result. Its structure is provider-specific.","properties":{"data":{"description":"The matched entity's data from the provider.","type":"object","additionalProperties":true},"sanctions":{"description":"Sanctions matches.","type":"array","items":{}},"adverse_media":{"description":"Adverse media matches.","type":"array","items":{}},"warnings":{"description":"Warning list matches.","type":"array","items":{}},"fitness_probity":{"description":"Fitness and probity matches.","type":"array","items":{}},"peps":{"description":"Politically exposed person (PEP) matches.","type":"object","additionalProperties":true},"is_muted":{"description":"Whether this result has been muted by a user.","type":"boolean"}}},"nullable":true}},"type":"object","nullable":true}},"type":"object"},"LinksResource":{"title":"Links Resource","properties":{"first":{"description":"URL of the first page of results.","type":"string","nullable":false},"last":{"description":"URL of the last page of results.","type":"string","nullable":false},"prev":{"description":"URL of the previous page of results, or null if there is none.","type":"string","nullable":true},"next":{"description":"URL of the next page of results, or null if there is none.","type":"string","nullable":true}},"type":"object"},"MetaResource":{"title":"Meta Resource","properties":{"current_page":{"description":"Number of the current page.","type":"integer","nullable":false},"from":{"description":"Position of the first item on this page, counted across all pages, or `null` if there are no results.","type":"integer","nullable":true},"last_page":{"description":"Number of the last page.","type":"integer","nullable":false},"links":{"description":"Pagination links, including links to the previous and next pages.","type":"array","items":{"properties":{"url":{"description":"URL of the page, or `null` if there is no such page.","type":"string","nullable":true},"label":{"description":"Text to display for the link, for example a page number or \"Previous\".","type":"string","nullable":false},"page":{"description":"Number of the page the link points to, or `null` if there is no such page.","type":"integer","nullable":true},"active":{"description":"Whether this link is for the current page.","type":"boolean","nullable":false}},"type":"object"},"nullable":false},"path":{"description":"Base URL of the endpoint, without query parameters.","type":"string","nullable":false},"per_page":{"description":"Number of items per page.","type":"integer","nullable":false},"to":{"description":"Position of the last item on this page, counted across all pages, or `null` if there are no results.","type":"integer","nullable":true},"total":{"description":"Total number of items across all pages.","type":"integer","nullable":false}},"type":"object"}},"responses":{"401":{"description":"Unauthorized. The access token is missing, invalid or has expired.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}},"429":{"description":"Too Many Requests. You have exceeded the rate limit. Wait for the number of seconds given in the `Retry-After` header before trying again.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}}}},"paths":{"/representatives":{"get":{"tags":["Representatives"],"summary":"List representatives","description":"Returns a list of representatives for your account. A representative can be a natural person or a legal entity, and may or may not be linked to a profile. The list includes representatives added through the portal or case management, and those converted from external data sources. Use the query parameters to filter the results.\n\nThe representative types are: `director`, `identity`, `ownership`, `declaratory`, `principal`, `director_company`, `treasurer`, `secretary`, `syndicator`, `member`, `agent`, `designated_member`, `club_manager`, `authorised_representative`, `authorised_signatory`, `trustee_company`, `trustee`, `partner_company`, `partner`, `syndicate_manager`, `individual`, `lead_partner`, `shareholder`, `shareholder_company`, `shareholder_entity`.","operationId":"4bc7424550b7b4dc4beb0dc398fad418","parameters":[{"$ref":"#/components/parameters/order_by"},{"name":"sort_by","in":"query","description":"The field to sort the results by. Use it together with `order_by` to choose the direction; if `order_by` is omitted, results are sorted in ascending order (`asc`). If `sort_by` is omitted, results are returned in no guaranteed order.\n\nSupported fields:\n- `created_at`\n- `updated_at`\n- `id`\n- `email`\n- `country`\n- `types` (a single value or a comma-separated list, for example `principal,director`)\n","schema":{"type":"string"}},{"$ref":"#/components/parameters/page"},{"name":"id","in":"query","description":"Filter by representative UUID. If a match is found, only that representative is returned.","schema":{"type":"string","format":"uuid"}},{"name":"is_company","in":"query","description":"Filter by whether the representative is a legal entity (`true`) or a natural person (`false`).","schema":{"type":"boolean"}},{"name":"customer_reference","in":"query","description":"Filter by the customer reference that was set when the profile was created.","schema":{"type":"string"}},{"name":"profile_id","in":"query","description":"Filter by profile UUID. Returns the representatives linked to that profile.","schema":{"type":"string","format":"uuid"}},{"name":"email","in":"query","description":"Filter by email address.","schema":{"type":"string"}},{"name":"types","in":"query","description":"Filter by representative type. To filter by more than one type, separate the types with commas, for example `principal,director`. A representative can have more than one type.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"properties":{"data":{"description":"List of representatives","type":"array","items":{"$ref":"#/components/schemas/RepresentativesResource"}},"links":{"$ref":"#/components/schemas/LinksResource"},"meta":{"$ref":"#/components/schemas/MetaResource"}},"type":"object"}}}},"401":{"$ref":"#/components/responses/401"},"429":{"$ref":"#/components/responses/429"}}}}}}
```

## Create a representative

> Creates a representative and links it to a profile. Include the \`profile\_id\` of the profile the representative will be linked to. Both natural persons and legal entities are supported.\
> \
> The representative types are: \`director\`, \`identity\`, \`ownership\`, \`declaratory\`, \`principal\`, \`director\_company\`, \`treasurer\`, \`secretary\`, \`syndicator\`, \`member\`, \`agent\`, \`designated\_member\`, \`club\_manager\`, \`authorised\_representative\`, \`authorised\_signatory\`, \`trustee\_company\`, \`trustee\`, \`partner\_company\`, \`partner\`, \`syndicate\_manager\`, \`individual\`, \`lead\_partner\`, \`shareholder\`, \`shareholder\_company\`, \`shareholder\_entity\`.

```json
{"openapi":"3.0.0","info":{"title":"Detected API","version":"v2"},"tags":[{"name":"Representatives","description":"Representatives are the people or entities associated with a profile, for example company directors, ultimate beneficial owners (UBOs), trustees, individuals, shareholder entities and director companies. A profile can have multiple representatives."}],"servers":[{"url":"https://api.detected.app/api/v2/public","description":"Production"}],"security":[{"AccessToken":[]}],"components":{"securitySchemes":{"AccessToken":{"type":"http","description":"The API uses OAuth 2.0. Request an access token with **Create an access token** (`POST /oauth/token`), sending the client ID and client secret of your integration client, and your account slug. Send the access token in the `Authorization` header of every request, in the format `Authorization: Bearer <access_token>`. The access token carries the scopes set on your integration client in the dashboard. Access tokens expire. When one expires, request a new one.","bearerFormat":"OAuth 2.0 access token","scheme":"bearer"}},"schemas":{"PersonCreateRequest":{"title":"Representative Create Request","required":["types","email","name","profile_id"],"properties":{"name":{"description":"Name of the representative.","required":["first_name","last_name"],"properties":{"first_name":{"description":"First name.","type":"string","nullable":false},"middle_name":{"description":"Middle name.","type":"string","nullable":false},"last_name":{"description":"Last name.","type":"string","nullable":false}},"type":"object","nullable":false},"email":{"description":"Email address of the representative.","type":"string","nullable":false},"title":{"description":"Title of the representative.","type":"string","enum":["Mr","Mrs","Ms","Miss","Mx","Dr","Rev"],"nullable":true},"profile_id":{"description":"UUID of the profile to link the representative to.","type":"string","format":"uuid","nullable":false},"review_status":{"description":"Review status of the representative.","type":"string","enum":["pending","needs_review","verified","rejected","fraud","additional_information","previously_verified"],"nullable":true},"types":{"description":"Types assigned to the representative. A representative can have more than one type.","type":"array","items":{"type":"string","enum":["director","identity","ownership","declaratory","principal","director_company","treasurer","secretary","syndicator","member","agent","designated_member","club_manager","authorised_representative","authorised_signatory","trustee_company","trustee","partner_company","partner","syndicate_manager","individual","lead_partner","shareholder","shareholder_company","shareholder_entity"]},"nullable":false},"dob":{"description":"Date of birth, in `YYYY-MM-DD` format.","type":"string","nullable":false},"role_type":{"description":"Role type of the representative.","type":"array","items":{"type":"string","enum":["Director","Designated Member","Partner","Company Principal","Other"]},"nullable":false},"professional_profile":{"description":"URL of the representative's professional profile.","type":"string","nullable":false},"job_title":{"description":"Job title.","type":"string","nullable":false},"residence_country_code":{"description":"Country of residence, ISO 3166-1 alpha-2 country code.","type":"string","nullable":false},"birth_country_code":{"description":"Country of birth, ISO 3166-1 alpha-2 country code.","type":"string","nullable":false},"nationality":{"description":"Nationality of the representative.","type":"string","nullable":false},"address":{"description":"Address of the representative.","properties":{"apartment_number":{"description":"Apartment number.","type":"string","nullable":false},"address_1":{"description":"First line of the address.","type":"string","nullable":false},"address_2":{"description":"Second line of the address.","type":"string","nullable":false},"city":{"description":"City.","type":"string","nullable":false},"state":{"description":"State or region.","type":"string","nullable":false},"postcode":{"description":"Postcode.","type":"string","nullable":false},"country":{"description":"Country of the address, ISO 3166-1 alpha-2 country code.","type":"string","nullable":false}},"type":"object","nullable":false},"personal_number":{"description":"Personal phone number.","type":"string","nullable":false},"shareholder_type":{"description":"Type of shareholding: `Direct` or `Indirect`.","type":"string","enum":["Direct","Indirect"],"nullable":false},"share_percentage":{"description":"Percentage of shares held by the representative.","type":"number","nullable":false}},"type":"object"},"RepresentativesResource":{"title":"Representative Resource","required":["id","profile_id","customer_reference","is_company","types"],"properties":{"id":{"description":"Representative UUID.","type":"string","nullable":false},"profile_id":{"description":"UUID of the profile the representative is linked to.","type":"string","format":"uuid","nullable":false},"customer_reference":{"description":"The customer reference of the profile the representative belongs to, as set when the profile was created.","type":"string","nullable":false},"is_company":{"description":"Whether the representative is a legal entity (`true`) or a natural person (`false`).","type":"boolean","nullable":false},"is_linked":{"description":"Whether the representative is linked to another representative record, either as the master or as a child of a link.","type":"boolean","nullable":false},"is_master_link":{"description":"Whether the representative is the master record of a representative link, i.e. other representative records are linked to it.","type":"boolean","nullable":false},"is_child_link":{"description":"Whether the representative is linked to a master representative record.","type":"boolean","nullable":false},"review_status":{"description":"Review status of the representative.","properties":{"status":{"description":"Current review status.","type":"string","enum":["pending","needs_review","verified","rejected","fraud","additional_information","previously_verified"],"nullable":false},"verified_at":{"description":"Date and time the representative was verified, or `null` if they have not been verified.","type":"string","nullable":true},"updated_at":{"description":"Date and time the review status was last updated.","type":"string","nullable":false},"created_at":{"description":"Date and time the review status was created.","type":"string","nullable":false}},"type":"object","nullable":true},"types":{"description":"Types assigned to the representative.","type":"array","items":{"type":"string","enum":["director","identity","ownership","declaratory","principal","director_company","treasurer","secretary","syndicator","member","agent","designated_member","club_manager","authorised_representative","authorised_signatory","trustee_company","trustee","partner_company","partner","syndicate_manager","individual","lead_partner","shareholder","shareholder_company","shareholder_entity"]},"nullable":false},"role_type":{"description":"Role types assigned to the representative: `Director`, `Designated Member`, `Partner`, `Company Principal` or `Other`.","type":"array","items":{"type":"string"},"nullable":true},"full_name":{"description":"Full name of the representative, or the company/legal entity name.","type":"string","nullable":true},"title":{"description":"Title of the representative, for example `Mr` or `Dr`.","type":"string","nullable":true},"professional_profile":{"description":"URL of the representative's professional profile.","type":"string","nullable":true},"country":{"description":"Name of the country of the address.","type":"string","nullable":true},"country_code":{"description":"Country of the address, ISO 3166-1 alpha-2 country code.","type":"string","nullable":true},"country_of_residence":{"description":"Name of the country of residence.","type":"string","nullable":true},"residence_country_code":{"description":"Country of residence, ISO 3166-1 alpha-2 country code.","type":"string","nullable":true},"personal_number":{"description":"Personal phone number.","type":"string","nullable":true},"first_name":{"description":"First name.","type":"string","nullable":true},"middle_name":{"description":"Middle name.","type":"string","nullable":true},"last_name":{"description":"Last name.","type":"string","nullable":true},"dob":{"description":"Date of birth, in `YYYY-MM-DD` format.","type":"string","nullable":true},"email":{"description":"Email address of the representative.","type":"string","nullable":true},"job_title":{"description":"Job title.","type":"string","nullable":true},"social_security_number":{"description":"US Social Security number of the representative, in the format `XXX-XX-XXXX`.","type":"string","nullable":true},"social_security_number_last_4":{"description":"Last 4 digits of the representative's US Social Security number.","type":"string","nullable":true},"passport_number":{"description":"Passport number.","type":"string","nullable":true},"landline_number":{"description":"Landline phone number.","type":"string","nullable":true},"apartment_number":{"description":"Apartment number.","type":"string","nullable":true},"address_1":{"description":"First line of the address.","type":"string","nullable":true},"address_2":{"description":"Second line of the address.","type":"string","nullable":true},"city":{"description":"City.","type":"string","nullable":true},"state":{"description":"State or region.","type":"string","nullable":true},"post_code":{"description":"Postcode.","type":"string","nullable":true},"country_of_birth":{"description":"Name of the country of birth.","type":"string","nullable":true},"birth_country_code":{"description":"Country of birth, ISO 3166-1 alpha-2 country code.","type":"string","nullable":true},"share_percentage":{"description":"Percentage of shares held by the representative.","type":"number","nullable":true},"shareholder_type":{"description":"Type of shareholding. `Direct` or `Indirect` for representatives created through the API; representatives imported from a data source may carry provider-specific values.","type":"string","nullable":true},"nationality":{"description":"Nationality.","type":"string","nullable":true},"nationality_code":{"description":"Nationality, ISO 3166-1 alpha-2 country code.","type":"string","nullable":true},"person_type_details":{"description":"Extra details that depend on the representative's type, such as the appointment date or ownership percentage. The fields returned depend on the representative's types (for example ownership percentages for owners, or company details for company representatives), and other fields may be returned.","properties":{"appointment_date":{"description":"Date the representative was appointed.","type":"string","nullable":true},"majority":{"description":"Whether the representative's ownership meets the majority threshold given in `majority_percentage`.","type":"boolean","nullable":true},"governing":{"description":"Whether the representative has a governing role.","type":"boolean","nullable":true},"responsibility":{"description":"Whether the representative has significant responsibility.","type":"boolean","nullable":true},"majority_percentage":{"description":"The majority ownership threshold percentage, taken from the portal configuration.","type":"string","nullable":true},"specific_ownership_percentage":{"description":"Percentage of the company owned by the representative.","type":"string","nullable":true},"direct_ownership_percentage":{"description":"Direct ownership percentage, or `null` if not available."},"indirect_ownership_percentage":{"description":"Indirect ownership percentage, or `null` if not available."},"beneficial_ownership_percentage":{"description":"Beneficial ownership percentage, or `null` if not available."},"implied_direct_ownership_percentage":{"description":"Implied direct ownership percentage, calculated through the ownership structure, or `null` if not available."},"implied_indirect_ownership_percentage":{"description":"Implied indirect ownership percentage, calculated through the ownership structure, or `null` if not available."},"implied_beneficial_ownership_percentage":{"description":"Implied beneficial ownership percentage, calculated through the ownership structure, or `null` if not available."},"degree_of_separation":{"description":"How many levels of ownership separate the representative from the profile's entity, or `null` if not available."},"company_name":{"description":"For company representatives, the company name.","type":"string"},"company_number":{"description":"For company representatives, the company registration number.","type":"string"},"full_address":{"description":"For company representatives, the registered address.","type":"string"},"trading_address":{"description":"For company representatives, the trading address.","type":"object","additionalProperties":true},"named_representative":{"description":"For company representatives, the named individual representing the company, or `null`.","type":"string","nullable":true},"is_active":{"description":"Whether the representative is currently active in the role, or `null` if not known."},"position_type":{"description":"Type of position held, or `null` if not known."},"resignation_date":{"description":"Date the representative resigned from the role, or `null` if they haven't."}},"type":"object","nullable":true,"additionalProperties":true},"copy_address":{"description":"Whether the trading address is the same as the registered address. Only set for `director_company` representatives.","type":"boolean","nullable":true},"updated_at":{"description":"Date and time the representative was last updated.","type":"string","nullable":true},"created_at":{"description":"Date and time the representative was created.","type":"string","nullable":true},"screenings":{"description":"AML screening results for the representative. Only returned by **Retrieve a representative** (`GET /representatives/{uuid}`); `null` if no screening has been run.","properties":{"details":{"description":"Details of the screening search that was performed.","properties":{"provider":{"description":"Screening provider the search was performed with.","type":"string","enum":["ion_group","comply_advantage","lseg_zfs"],"nullable":false},"performed_at":{"description":"Date the screening was performed.","type":"string","nullable":false},"search_term":{"description":"Term the representative was searched with against the provider.","type":"string","nullable":false},"search_payload":{"description":"The search sent to the screening provider. Its structure is provider-specific."},"is_monitored":{"description":"Whether the representative is enrolled in ongoing monitoring with the provider.","type":"boolean","nullable":false}},"type":"object","nullable":false},"screenings":{"description":"List of screening matches returned by the provider.","type":"array","items":{"type":"object","additionalProperties":true,"description":"One screening result. Its structure is provider-specific.","properties":{"data":{"description":"The matched entity's data from the provider.","type":"object","additionalProperties":true},"sanctions":{"description":"Sanctions matches.","type":"array","items":{}},"adverse_media":{"description":"Adverse media matches.","type":"array","items":{}},"warnings":{"description":"Warning list matches.","type":"array","items":{}},"fitness_probity":{"description":"Fitness and probity matches.","type":"array","items":{}},"peps":{"description":"Politically exposed person (PEP) matches.","type":"object","additionalProperties":true},"is_muted":{"description":"Whether this result has been muted by a user.","type":"boolean"}}},"nullable":true}},"type":"object","nullable":true}},"type":"object"}},"headers":{"X-RateLimit-Limit":{"description":"Maximum number of requests allowed in the rate limit window.","schema":{"type":"number","nullable":false}},"X-RateLimit-Remaining":{"description":"Number of requests remaining in the current rate limit window.","schema":{"type":"number","nullable":false}},"Retry-After":{"description":"Number of seconds to wait before making another request. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}},"X-RateLimit-Reset":{"description":"Unix timestamp (in seconds) at which the rate limit resets. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}}},"responses":{"400":{"description":"Bad Request. The request could not be processed because it is invalid. The `message` field explains why.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}},"401":{"description":"Unauthorized. The access token is missing, invalid or has expired.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}},"422":{"description":"Unprocessable Content. The request was understood but failed validation. `errors` lists each field that failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"description":"A human-readable description of the first error.","type":"string"},"errors":{"description":"Validation errors, keyed by the name of the field that failed. Each field has a list of messages.","type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}},"429":{"description":"Too Many Requests. You have exceeded the rate limit. Wait for the number of seconds given in the `Retry-After` header before trying again.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}}}},"paths":{"/representatives":{"post":{"tags":["Representatives"],"summary":"Create a representative","description":"Creates a representative and links it to a profile. Include the `profile_id` of the profile the representative will be linked to. Both natural persons and legal entities are supported.\n\nThe representative types are: `director`, `identity`, `ownership`, `declaratory`, `principal`, `director_company`, `treasurer`, `secretary`, `syndicator`, `member`, `agent`, `designated_member`, `club_manager`, `authorised_representative`, `authorised_signatory`, `trustee_company`, `trustee`, `partner_company`, `partner`, `syndicate_manager`, `individual`, `lead_partner`, `shareholder`, `shareholder_company`, `shareholder_entity`.","operationId":"b541cddd0764f6924d11b4ff787ae9ec","parameters":[{"name":"screen","in":"query","description":"Whether to run AML screening on the representative when they are added. Send `1` to screen the representative, or `0` to add them without screening. The default is `1`.","schema":{"type":"integer","enum":[0,1]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonCreateRequest"}}}},"responses":{"201":{"description":"Created","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/RepresentativesResource"}},"type":"object"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}}}}}}
```

## Retrieve a representative

> Returns a single representative, including their review status, type details and AML screening results.

```json
{"openapi":"3.0.0","info":{"title":"Detected API","version":"v2"},"tags":[{"name":"Representatives","description":"Representatives are the people or entities associated with a profile, for example company directors, ultimate beneficial owners (UBOs), trustees, individuals, shareholder entities and director companies. A profile can have multiple representatives."}],"servers":[{"url":"https://api.detected.app/api/v2/public","description":"Production"}],"security":[{"AccessToken":[]}],"components":{"securitySchemes":{"AccessToken":{"type":"http","description":"The API uses OAuth 2.0. Request an access token with **Create an access token** (`POST /oauth/token`), sending the client ID and client secret of your integration client, and your account slug. Send the access token in the `Authorization` header of every request, in the format `Authorization: Bearer <access_token>`. The access token carries the scopes set on your integration client in the dashboard. Access tokens expire. When one expires, request a new one.","bearerFormat":"OAuth 2.0 access token","scheme":"bearer"}},"parameters":{"representativeUuid":{"name":"uuid","in":"path","description":"UUID of the representative.","required":true,"schema":{"type":"string","format":"uuid","nullable":false}}},"headers":{"X-RateLimit-Limit":{"description":"Maximum number of requests allowed in the rate limit window.","schema":{"type":"number","nullable":false}},"X-RateLimit-Remaining":{"description":"Number of requests remaining in the current rate limit window.","schema":{"type":"number","nullable":false}},"Retry-After":{"description":"Number of seconds to wait before making another request. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}},"X-RateLimit-Reset":{"description":"Unix timestamp (in seconds) at which the rate limit resets. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}}},"schemas":{"RepresentativesResource":{"title":"Representative Resource","required":["id","profile_id","customer_reference","is_company","types"],"properties":{"id":{"description":"Representative UUID.","type":"string","nullable":false},"profile_id":{"description":"UUID of the profile the representative is linked to.","type":"string","format":"uuid","nullable":false},"customer_reference":{"description":"The customer reference of the profile the representative belongs to, as set when the profile was created.","type":"string","nullable":false},"is_company":{"description":"Whether the representative is a legal entity (`true`) or a natural person (`false`).","type":"boolean","nullable":false},"is_linked":{"description":"Whether the representative is linked to another representative record, either as the master or as a child of a link.","type":"boolean","nullable":false},"is_master_link":{"description":"Whether the representative is the master record of a representative link, i.e. other representative records are linked to it.","type":"boolean","nullable":false},"is_child_link":{"description":"Whether the representative is linked to a master representative record.","type":"boolean","nullable":false},"review_status":{"description":"Review status of the representative.","properties":{"status":{"description":"Current review status.","type":"string","enum":["pending","needs_review","verified","rejected","fraud","additional_information","previously_verified"],"nullable":false},"verified_at":{"description":"Date and time the representative was verified, or `null` if they have not been verified.","type":"string","nullable":true},"updated_at":{"description":"Date and time the review status was last updated.","type":"string","nullable":false},"created_at":{"description":"Date and time the review status was created.","type":"string","nullable":false}},"type":"object","nullable":true},"types":{"description":"Types assigned to the representative.","type":"array","items":{"type":"string","enum":["director","identity","ownership","declaratory","principal","director_company","treasurer","secretary","syndicator","member","agent","designated_member","club_manager","authorised_representative","authorised_signatory","trustee_company","trustee","partner_company","partner","syndicate_manager","individual","lead_partner","shareholder","shareholder_company","shareholder_entity"]},"nullable":false},"role_type":{"description":"Role types assigned to the representative: `Director`, `Designated Member`, `Partner`, `Company Principal` or `Other`.","type":"array","items":{"type":"string"},"nullable":true},"full_name":{"description":"Full name of the representative, or the company/legal entity name.","type":"string","nullable":true},"title":{"description":"Title of the representative, for example `Mr` or `Dr`.","type":"string","nullable":true},"professional_profile":{"description":"URL of the representative's professional profile.","type":"string","nullable":true},"country":{"description":"Name of the country of the address.","type":"string","nullable":true},"country_code":{"description":"Country of the address, ISO 3166-1 alpha-2 country code.","type":"string","nullable":true},"country_of_residence":{"description":"Name of the country of residence.","type":"string","nullable":true},"residence_country_code":{"description":"Country of residence, ISO 3166-1 alpha-2 country code.","type":"string","nullable":true},"personal_number":{"description":"Personal phone number.","type":"string","nullable":true},"first_name":{"description":"First name.","type":"string","nullable":true},"middle_name":{"description":"Middle name.","type":"string","nullable":true},"last_name":{"description":"Last name.","type":"string","nullable":true},"dob":{"description":"Date of birth, in `YYYY-MM-DD` format.","type":"string","nullable":true},"email":{"description":"Email address of the representative.","type":"string","nullable":true},"job_title":{"description":"Job title.","type":"string","nullable":true},"social_security_number":{"description":"US Social Security number of the representative, in the format `XXX-XX-XXXX`.","type":"string","nullable":true},"social_security_number_last_4":{"description":"Last 4 digits of the representative's US Social Security number.","type":"string","nullable":true},"passport_number":{"description":"Passport number.","type":"string","nullable":true},"landline_number":{"description":"Landline phone number.","type":"string","nullable":true},"apartment_number":{"description":"Apartment number.","type":"string","nullable":true},"address_1":{"description":"First line of the address.","type":"string","nullable":true},"address_2":{"description":"Second line of the address.","type":"string","nullable":true},"city":{"description":"City.","type":"string","nullable":true},"state":{"description":"State or region.","type":"string","nullable":true},"post_code":{"description":"Postcode.","type":"string","nullable":true},"country_of_birth":{"description":"Name of the country of birth.","type":"string","nullable":true},"birth_country_code":{"description":"Country of birth, ISO 3166-1 alpha-2 country code.","type":"string","nullable":true},"share_percentage":{"description":"Percentage of shares held by the representative.","type":"number","nullable":true},"shareholder_type":{"description":"Type of shareholding. `Direct` or `Indirect` for representatives created through the API; representatives imported from a data source may carry provider-specific values.","type":"string","nullable":true},"nationality":{"description":"Nationality.","type":"string","nullable":true},"nationality_code":{"description":"Nationality, ISO 3166-1 alpha-2 country code.","type":"string","nullable":true},"person_type_details":{"description":"Extra details that depend on the representative's type, such as the appointment date or ownership percentage. The fields returned depend on the representative's types (for example ownership percentages for owners, or company details for company representatives), and other fields may be returned.","properties":{"appointment_date":{"description":"Date the representative was appointed.","type":"string","nullable":true},"majority":{"description":"Whether the representative's ownership meets the majority threshold given in `majority_percentage`.","type":"boolean","nullable":true},"governing":{"description":"Whether the representative has a governing role.","type":"boolean","nullable":true},"responsibility":{"description":"Whether the representative has significant responsibility.","type":"boolean","nullable":true},"majority_percentage":{"description":"The majority ownership threshold percentage, taken from the portal configuration.","type":"string","nullable":true},"specific_ownership_percentage":{"description":"Percentage of the company owned by the representative.","type":"string","nullable":true},"direct_ownership_percentage":{"description":"Direct ownership percentage, or `null` if not available."},"indirect_ownership_percentage":{"description":"Indirect ownership percentage, or `null` if not available."},"beneficial_ownership_percentage":{"description":"Beneficial ownership percentage, or `null` if not available."},"implied_direct_ownership_percentage":{"description":"Implied direct ownership percentage, calculated through the ownership structure, or `null` if not available."},"implied_indirect_ownership_percentage":{"description":"Implied indirect ownership percentage, calculated through the ownership structure, or `null` if not available."},"implied_beneficial_ownership_percentage":{"description":"Implied beneficial ownership percentage, calculated through the ownership structure, or `null` if not available."},"degree_of_separation":{"description":"How many levels of ownership separate the representative from the profile's entity, or `null` if not available."},"company_name":{"description":"For company representatives, the company name.","type":"string"},"company_number":{"description":"For company representatives, the company registration number.","type":"string"},"full_address":{"description":"For company representatives, the registered address.","type":"string"},"trading_address":{"description":"For company representatives, the trading address.","type":"object","additionalProperties":true},"named_representative":{"description":"For company representatives, the named individual representing the company, or `null`.","type":"string","nullable":true},"is_active":{"description":"Whether the representative is currently active in the role, or `null` if not known."},"position_type":{"description":"Type of position held, or `null` if not known."},"resignation_date":{"description":"Date the representative resigned from the role, or `null` if they haven't."}},"type":"object","nullable":true,"additionalProperties":true},"copy_address":{"description":"Whether the trading address is the same as the registered address. Only set for `director_company` representatives.","type":"boolean","nullable":true},"updated_at":{"description":"Date and time the representative was last updated.","type":"string","nullable":true},"created_at":{"description":"Date and time the representative was created.","type":"string","nullable":true},"screenings":{"description":"AML screening results for the representative. Only returned by **Retrieve a representative** (`GET /representatives/{uuid}`); `null` if no screening has been run.","properties":{"details":{"description":"Details of the screening search that was performed.","properties":{"provider":{"description":"Screening provider the search was performed with.","type":"string","enum":["ion_group","comply_advantage","lseg_zfs"],"nullable":false},"performed_at":{"description":"Date the screening was performed.","type":"string","nullable":false},"search_term":{"description":"Term the representative was searched with against the provider.","type":"string","nullable":false},"search_payload":{"description":"The search sent to the screening provider. Its structure is provider-specific."},"is_monitored":{"description":"Whether the representative is enrolled in ongoing monitoring with the provider.","type":"boolean","nullable":false}},"type":"object","nullable":false},"screenings":{"description":"List of screening matches returned by the provider.","type":"array","items":{"type":"object","additionalProperties":true,"description":"One screening result. Its structure is provider-specific.","properties":{"data":{"description":"The matched entity's data from the provider.","type":"object","additionalProperties":true},"sanctions":{"description":"Sanctions matches.","type":"array","items":{}},"adverse_media":{"description":"Adverse media matches.","type":"array","items":{}},"warnings":{"description":"Warning list matches.","type":"array","items":{}},"fitness_probity":{"description":"Fitness and probity matches.","type":"array","items":{}},"peps":{"description":"Politically exposed person (PEP) matches.","type":"object","additionalProperties":true},"is_muted":{"description":"Whether this result has been muted by a user.","type":"boolean"}}},"nullable":true}},"type":"object","nullable":true}},"type":"object"}},"responses":{"401":{"description":"Unauthorized. The access token is missing, invalid or has expired.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}},"404":{"description":"Not Found. The requested resource does not exist, or is not available to your account.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"},"error":{"description":"Machine-readable details of the error.","type":"object","properties":{"key":{"description":"Error code, for example `error.generic`.","type":"string"},"params":{"description":"Values used in the error message, if any.","type":"array","items":{}}}}},"type":"object"}}}},"429":{"description":"Too Many Requests. You have exceeded the rate limit. Wait for the number of seconds given in the `Retry-After` header before trying again.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}}}},"paths":{"/representatives/{uuid}":{"get":{"tags":["Representatives"],"summary":"Retrieve a representative","description":"Returns a single representative, including their review status, type details and AML screening results.","operationId":"5be1b0c7c945a48fe0566e9b6778c6d9","parameters":[{"$ref":"#/components/parameters/representativeUuid"}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/RepresentativesResource"}},"type":"object"}}}},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"}}}}}}
```

## Delete a representative

> Deletes a representative. This cannot be undone. Screening monitoring for the representative is stopped before the deletion.

```json
{"openapi":"3.0.0","info":{"title":"Detected API","version":"v2"},"tags":[{"name":"Representatives","description":"Representatives are the people or entities associated with a profile, for example company directors, ultimate beneficial owners (UBOs), trustees, individuals, shareholder entities and director companies. A profile can have multiple representatives."}],"servers":[{"url":"https://api.detected.app/api/v2/public","description":"Production"}],"security":[{"AccessToken":[]}],"components":{"securitySchemes":{"AccessToken":{"type":"http","description":"The API uses OAuth 2.0. Request an access token with **Create an access token** (`POST /oauth/token`), sending the client ID and client secret of your integration client, and your account slug. Send the access token in the `Authorization` header of every request, in the format `Authorization: Bearer <access_token>`. The access token carries the scopes set on your integration client in the dashboard. Access tokens expire. When one expires, request a new one.","bearerFormat":"OAuth 2.0 access token","scheme":"bearer"}},"parameters":{"representativeUuid":{"name":"uuid","in":"path","description":"UUID of the representative.","required":true,"schema":{"type":"string","format":"uuid","nullable":false}}},"headers":{"X-RateLimit-Limit":{"description":"Maximum number of requests allowed in the rate limit window.","schema":{"type":"number","nullable":false}},"X-RateLimit-Remaining":{"description":"Number of requests remaining in the current rate limit window.","schema":{"type":"number","nullable":false}},"Retry-After":{"description":"Number of seconds to wait before making another request. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}},"X-RateLimit-Reset":{"description":"Unix timestamp (in seconds) at which the rate limit resets. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}}},"responses":{"401":{"description":"Unauthorized. The access token is missing, invalid or has expired.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}},"404":{"description":"Not Found. The requested resource does not exist, or is not available to your account.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"},"error":{"description":"Machine-readable details of the error.","type":"object","properties":{"key":{"description":"Error code, for example `error.generic`.","type":"string"},"params":{"description":"Values used in the error message, if any.","type":"array","items":{}}}}},"type":"object"}}}},"429":{"description":"Too Many Requests. You have exceeded the rate limit. Wait for the number of seconds given in the `Retry-After` header before trying again.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}}}},"paths":{"/representatives/{uuid}":{"delete":{"tags":["Representatives"],"summary":"Delete a representative","description":"Deletes a representative. This cannot be undone. Screening monitoring for the representative is stopped before the deletion.","operationId":"c03da3c04eb4c3a1f8ab9231c4d85889","parameters":[{"$ref":"#/components/parameters/representativeUuid"}],"responses":{"204":{"description":"No Content. The representative was deleted.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}}},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"}}}}}}
```

## Update a representative

> Updates a representative. All fields are optional; omitted fields keep their current values. Types sent in \`types\` are added to the representative's existing types.

```json
{"openapi":"3.0.0","info":{"title":"Detected API","version":"v2"},"tags":[{"name":"Representatives","description":"Representatives are the people or entities associated with a profile, for example company directors, ultimate beneficial owners (UBOs), trustees, individuals, shareholder entities and director companies. A profile can have multiple representatives."}],"servers":[{"url":"https://api.detected.app/api/v2/public","description":"Production"}],"security":[{"AccessToken":[]}],"components":{"securitySchemes":{"AccessToken":{"type":"http","description":"The API uses OAuth 2.0. Request an access token with **Create an access token** (`POST /oauth/token`), sending the client ID and client secret of your integration client, and your account slug. Send the access token in the `Authorization` header of every request, in the format `Authorization: Bearer <access_token>`. The access token carries the scopes set on your integration client in the dashboard. Access tokens expire. When one expires, request a new one.","bearerFormat":"OAuth 2.0 access token","scheme":"bearer"}},"parameters":{"representativeUuid":{"name":"uuid","in":"path","description":"UUID of the representative.","required":true,"schema":{"type":"string","format":"uuid","nullable":false}}},"schemas":{"PersonUpdateRequest":{"title":"Representative Update Request","description":"Changes to a representative. All fields are optional; omitted fields keep their current values.","properties":{"name":{"description":"Name of the representative.","properties":{"first_name":{"description":"First name.","type":"string","nullable":false},"middle_name":{"description":"Middle name.","type":"string","nullable":false},"last_name":{"description":"Last name.","type":"string","nullable":false}},"type":"object","nullable":false},"email":{"description":"Email address of the representative.","type":"string","nullable":false},"title":{"description":"Title of the representative.","type":"string","enum":["Mr","Mrs","Ms","Miss","Mx","Dr","Rev"],"nullable":true},"review_status":{"description":"Review status of the representative.","type":"string","enum":["pending","needs_review","verified","rejected","fraud","additional_information","previously_verified"],"nullable":true},"types":{"description":"Types assigned to the representative. A representative can have more than one type. Types sent here are added to the representative's existing types.","type":"array","items":{"type":"string","enum":["director","identity","ownership","declaratory","principal","director_company","treasurer","secretary","syndicator","member","agent","designated_member","club_manager","authorised_representative","authorised_signatory","trustee_company","trustee","partner_company","partner","syndicate_manager","individual","lead_partner","shareholder","shareholder_company","shareholder_entity"]},"nullable":false},"dob":{"description":"Date of birth, in `YYYY-MM-DD` format.","type":"string","nullable":false},"role_type":{"description":"Role type of the representative.","type":"array","items":{"type":"string","enum":["Director","Designated Member","Partner","Company Principal","Other"]},"nullable":false},"professional_profile":{"description":"URL of the representative's professional profile.","type":"string","nullable":false},"job_title":{"description":"Job title.","type":"string","nullable":false},"residence_country_code":{"description":"Country of residence, ISO 3166-1 alpha-2 country code.","type":"string","nullable":false},"birth_country_code":{"description":"Country of birth, ISO 3166-1 alpha-2 country code.","type":"string","nullable":false},"nationality":{"description":"Nationality of the representative.","type":"string","nullable":false},"address":{"description":"Address of the representative.","properties":{"apartment_number":{"description":"Apartment number.","type":"string","nullable":false},"address_1":{"description":"First line of the address.","type":"string","nullable":false},"address_2":{"description":"Second line of the address.","type":"string","nullable":false},"city":{"description":"City.","type":"string","nullable":false},"state":{"description":"State or region.","type":"string","nullable":false},"postcode":{"description":"Postcode.","type":"string","nullable":false},"country":{"description":"Country of the address, ISO 3166-1 alpha-2 country code.","type":"string","nullable":false}},"type":"object","nullable":false},"personal_number":{"description":"Personal phone number.","type":"string","nullable":false},"shareholder_type":{"description":"Type of shareholding: `Direct` or `Indirect`.","type":"string","enum":["Direct","Indirect"],"nullable":false},"share_percentage":{"description":"Percentage of shares held by the representative.","type":"number","nullable":false}},"type":"object"},"RepresentativesResource":{"title":"Representative Resource","required":["id","profile_id","customer_reference","is_company","types"],"properties":{"id":{"description":"Representative UUID.","type":"string","nullable":false},"profile_id":{"description":"UUID of the profile the representative is linked to.","type":"string","format":"uuid","nullable":false},"customer_reference":{"description":"The customer reference of the profile the representative belongs to, as set when the profile was created.","type":"string","nullable":false},"is_company":{"description":"Whether the representative is a legal entity (`true`) or a natural person (`false`).","type":"boolean","nullable":false},"is_linked":{"description":"Whether the representative is linked to another representative record, either as the master or as a child of a link.","type":"boolean","nullable":false},"is_master_link":{"description":"Whether the representative is the master record of a representative link, i.e. other representative records are linked to it.","type":"boolean","nullable":false},"is_child_link":{"description":"Whether the representative is linked to a master representative record.","type":"boolean","nullable":false},"review_status":{"description":"Review status of the representative.","properties":{"status":{"description":"Current review status.","type":"string","enum":["pending","needs_review","verified","rejected","fraud","additional_information","previously_verified"],"nullable":false},"verified_at":{"description":"Date and time the representative was verified, or `null` if they have not been verified.","type":"string","nullable":true},"updated_at":{"description":"Date and time the review status was last updated.","type":"string","nullable":false},"created_at":{"description":"Date and time the review status was created.","type":"string","nullable":false}},"type":"object","nullable":true},"types":{"description":"Types assigned to the representative.","type":"array","items":{"type":"string","enum":["director","identity","ownership","declaratory","principal","director_company","treasurer","secretary","syndicator","member","agent","designated_member","club_manager","authorised_representative","authorised_signatory","trustee_company","trustee","partner_company","partner","syndicate_manager","individual","lead_partner","shareholder","shareholder_company","shareholder_entity"]},"nullable":false},"role_type":{"description":"Role types assigned to the representative: `Director`, `Designated Member`, `Partner`, `Company Principal` or `Other`.","type":"array","items":{"type":"string"},"nullable":true},"full_name":{"description":"Full name of the representative, or the company/legal entity name.","type":"string","nullable":true},"title":{"description":"Title of the representative, for example `Mr` or `Dr`.","type":"string","nullable":true},"professional_profile":{"description":"URL of the representative's professional profile.","type":"string","nullable":true},"country":{"description":"Name of the country of the address.","type":"string","nullable":true},"country_code":{"description":"Country of the address, ISO 3166-1 alpha-2 country code.","type":"string","nullable":true},"country_of_residence":{"description":"Name of the country of residence.","type":"string","nullable":true},"residence_country_code":{"description":"Country of residence, ISO 3166-1 alpha-2 country code.","type":"string","nullable":true},"personal_number":{"description":"Personal phone number.","type":"string","nullable":true},"first_name":{"description":"First name.","type":"string","nullable":true},"middle_name":{"description":"Middle name.","type":"string","nullable":true},"last_name":{"description":"Last name.","type":"string","nullable":true},"dob":{"description":"Date of birth, in `YYYY-MM-DD` format.","type":"string","nullable":true},"email":{"description":"Email address of the representative.","type":"string","nullable":true},"job_title":{"description":"Job title.","type":"string","nullable":true},"social_security_number":{"description":"US Social Security number of the representative, in the format `XXX-XX-XXXX`.","type":"string","nullable":true},"social_security_number_last_4":{"description":"Last 4 digits of the representative's US Social Security number.","type":"string","nullable":true},"passport_number":{"description":"Passport number.","type":"string","nullable":true},"landline_number":{"description":"Landline phone number.","type":"string","nullable":true},"apartment_number":{"description":"Apartment number.","type":"string","nullable":true},"address_1":{"description":"First line of the address.","type":"string","nullable":true},"address_2":{"description":"Second line of the address.","type":"string","nullable":true},"city":{"description":"City.","type":"string","nullable":true},"state":{"description":"State or region.","type":"string","nullable":true},"post_code":{"description":"Postcode.","type":"string","nullable":true},"country_of_birth":{"description":"Name of the country of birth.","type":"string","nullable":true},"birth_country_code":{"description":"Country of birth, ISO 3166-1 alpha-2 country code.","type":"string","nullable":true},"share_percentage":{"description":"Percentage of shares held by the representative.","type":"number","nullable":true},"shareholder_type":{"description":"Type of shareholding. `Direct` or `Indirect` for representatives created through the API; representatives imported from a data source may carry provider-specific values.","type":"string","nullable":true},"nationality":{"description":"Nationality.","type":"string","nullable":true},"nationality_code":{"description":"Nationality, ISO 3166-1 alpha-2 country code.","type":"string","nullable":true},"person_type_details":{"description":"Extra details that depend on the representative's type, such as the appointment date or ownership percentage. The fields returned depend on the representative's types (for example ownership percentages for owners, or company details for company representatives), and other fields may be returned.","properties":{"appointment_date":{"description":"Date the representative was appointed.","type":"string","nullable":true},"majority":{"description":"Whether the representative's ownership meets the majority threshold given in `majority_percentage`.","type":"boolean","nullable":true},"governing":{"description":"Whether the representative has a governing role.","type":"boolean","nullable":true},"responsibility":{"description":"Whether the representative has significant responsibility.","type":"boolean","nullable":true},"majority_percentage":{"description":"The majority ownership threshold percentage, taken from the portal configuration.","type":"string","nullable":true},"specific_ownership_percentage":{"description":"Percentage of the company owned by the representative.","type":"string","nullable":true},"direct_ownership_percentage":{"description":"Direct ownership percentage, or `null` if not available."},"indirect_ownership_percentage":{"description":"Indirect ownership percentage, or `null` if not available."},"beneficial_ownership_percentage":{"description":"Beneficial ownership percentage, or `null` if not available."},"implied_direct_ownership_percentage":{"description":"Implied direct ownership percentage, calculated through the ownership structure, or `null` if not available."},"implied_indirect_ownership_percentage":{"description":"Implied indirect ownership percentage, calculated through the ownership structure, or `null` if not available."},"implied_beneficial_ownership_percentage":{"description":"Implied beneficial ownership percentage, calculated through the ownership structure, or `null` if not available."},"degree_of_separation":{"description":"How many levels of ownership separate the representative from the profile's entity, or `null` if not available."},"company_name":{"description":"For company representatives, the company name.","type":"string"},"company_number":{"description":"For company representatives, the company registration number.","type":"string"},"full_address":{"description":"For company representatives, the registered address.","type":"string"},"trading_address":{"description":"For company representatives, the trading address.","type":"object","additionalProperties":true},"named_representative":{"description":"For company representatives, the named individual representing the company, or `null`.","type":"string","nullable":true},"is_active":{"description":"Whether the representative is currently active in the role, or `null` if not known."},"position_type":{"description":"Type of position held, or `null` if not known."},"resignation_date":{"description":"Date the representative resigned from the role, or `null` if they haven't."}},"type":"object","nullable":true,"additionalProperties":true},"copy_address":{"description":"Whether the trading address is the same as the registered address. Only set for `director_company` representatives.","type":"boolean","nullable":true},"updated_at":{"description":"Date and time the representative was last updated.","type":"string","nullable":true},"created_at":{"description":"Date and time the representative was created.","type":"string","nullable":true},"screenings":{"description":"AML screening results for the representative. Only returned by **Retrieve a representative** (`GET /representatives/{uuid}`); `null` if no screening has been run.","properties":{"details":{"description":"Details of the screening search that was performed.","properties":{"provider":{"description":"Screening provider the search was performed with.","type":"string","enum":["ion_group","comply_advantage","lseg_zfs"],"nullable":false},"performed_at":{"description":"Date the screening was performed.","type":"string","nullable":false},"search_term":{"description":"Term the representative was searched with against the provider.","type":"string","nullable":false},"search_payload":{"description":"The search sent to the screening provider. Its structure is provider-specific."},"is_monitored":{"description":"Whether the representative is enrolled in ongoing monitoring with the provider.","type":"boolean","nullable":false}},"type":"object","nullable":false},"screenings":{"description":"List of screening matches returned by the provider.","type":"array","items":{"type":"object","additionalProperties":true,"description":"One screening result. Its structure is provider-specific.","properties":{"data":{"description":"The matched entity's data from the provider.","type":"object","additionalProperties":true},"sanctions":{"description":"Sanctions matches.","type":"array","items":{}},"adverse_media":{"description":"Adverse media matches.","type":"array","items":{}},"warnings":{"description":"Warning list matches.","type":"array","items":{}},"fitness_probity":{"description":"Fitness and probity matches.","type":"array","items":{}},"peps":{"description":"Politically exposed person (PEP) matches.","type":"object","additionalProperties":true},"is_muted":{"description":"Whether this result has been muted by a user.","type":"boolean"}}},"nullable":true}},"type":"object","nullable":true}},"type":"object"}},"headers":{"X-RateLimit-Limit":{"description":"Maximum number of requests allowed in the rate limit window.","schema":{"type":"number","nullable":false}},"X-RateLimit-Remaining":{"description":"Number of requests remaining in the current rate limit window.","schema":{"type":"number","nullable":false}},"Retry-After":{"description":"Number of seconds to wait before making another request. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}},"X-RateLimit-Reset":{"description":"Unix timestamp (in seconds) at which the rate limit resets. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}}},"responses":{"400":{"description":"Bad Request. The request could not be processed because it is invalid. The `message` field explains why.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}},"401":{"description":"Unauthorized. The access token is missing, invalid or has expired.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}},"404":{"description":"Not Found. The requested resource does not exist, or is not available to your account.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"},"error":{"description":"Machine-readable details of the error.","type":"object","properties":{"key":{"description":"Error code, for example `error.generic`.","type":"string"},"params":{"description":"Values used in the error message, if any.","type":"array","items":{}}}}},"type":"object"}}}},"422":{"description":"Unprocessable Content. The request was understood but failed validation. `errors` lists each field that failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"description":"A human-readable description of the first error.","type":"string"},"errors":{"description":"Validation errors, keyed by the name of the field that failed. Each field has a list of messages.","type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}},"429":{"description":"Too Many Requests. You have exceeded the rate limit. Wait for the number of seconds given in the `Retry-After` header before trying again.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}}}},"paths":{"/representatives/{uuid}":{"patch":{"tags":["Representatives"],"summary":"Update a representative","description":"Updates a representative. All fields are optional; omitted fields keep their current values. Types sent in `types` are added to the representative's existing types.","operationId":"073a2ef443ca6ac486b9af42a062cdc0","parameters":[{"$ref":"#/components/parameters/representativeUuid"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonUpdateRequest"}}}},"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/RepresentativesResource"}},"type":"object"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://detected.gitbook.io/detected-api-docs/api-reference/representatives.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.