Skip to content
straddle API Docs
Get started
API Reference
Embed

Representatives

Representatives are individuals who have legal authority or significant responsibility within a business entity associated with a Straddle account. Each representative undergoes automated verification as part of KYC/KYB compliance. Use representatives to collect and verify beneficial owners, control persons, and authorized signers required for account onboarding. Representatives also determine who can legally operate the account and make important changes.

Create a representative
embed.representatives.create(RepresentativeCreateParams**kwargs) -> Representative
POST/v1/representatives
List representatives
embed.representatives.list(RepresentativeListParams**kwargs) -> SyncPageNumberSchema[Data]
GET/v1/representatives
Update a representative
embed.representatives.update(strrepresentative_id, RepresentativeUpdateParams**kwargs) -> Representative
PUT/v1/representatives/{representative_id}
Lookup a representative
embed.representatives.get(strrepresentative_id, RepresentativeGetParams**kwargs) -> Representative
GET/v1/representatives/{representative_id}
Retrieve unmasked representative details
embed.representatives.unmask(strrepresentative_id, RepresentativeUnmaskParams**kwargs) -> Representative
GET/v1/representatives/{representative_id}/unmask
ModelsExpand Collapse
class Representative: …
data: Data
id: str

Unique identifier for the representative.

formatuuid
account_id: str

The unique identifier of the account this representative is associated with.

formatuuid
created_at: datetime

Timestamp of when the representative was created.

formatdate-time
dob: date

The date of birth of the representative, in ISO 8601 format (YYYY-MM-DD).

formatdate
email: Optional[str]

The email address of the representative.

formatemail
first_name: str

The first name of the representative.

last_name: str

The last name of the representative.

mobile_number: str

The mobile phone number of the representative.

name: str
relationship: DataRelationship
control: bool

Whether the representative has significant responsibility to control, manage, or direct the organization. One representative must be identified under the control prong for each legal entity.

owner: bool

Whether the representative owns any percentage of of the equity interests of the legal entity.

primary: bool

Whether the person is authorized as the primary representative of the account. This is the person chosen by the business to provide information about themselves, general information about the account, and who consented to the services agreement.

There can be only one primary representative for an account at a time.

percent_ownership: Optional[float]

The percentage of ownership the representative has. Required if 'Owner' is true.

formatdouble
title: Optional[str]

The job title of the representative.

ssn_last4: str

The last 4 digits of the representative's Social Security Number.

status: Literal["created", "onboarding", "active", 2 more]

The current status of the representative.

One of the following:
"created"
"onboarding"
"active"
"rejected"
"inactive"
status_detail: DataStatusDetail
code: str

A machine-readable code for the specific status, useful for programmatic handling.

message: str

A human-readable message describing the current status.

reason: Literal["unverified", "in_review", "pending", 5 more]

A machine-readable identifier for the specific status, useful for programmatic handling.

One of the following:
"unverified"
"in_review"
"pending"
"stuck"
"verified"
"failed_verification"
"disabled"
"new"
source: Literal["watchtower"]

Identifies the origin of the status change (e.g., watchtower). This helps in tracking the cause of status updates.

updated_at: datetime

Timestamp of the most recent update to the representative.

formatdate-time
external_id: Optional[str]

Unique identifier for the representative in your database, used for cross-referencing between Straddle and your systems.

metadata: Optional[Dict[str, str]]

Up to 20 additional user-defined key-value pairs. Useful for storing additional information about the represetative in a structured format.

phone: Optional[str]
user_id: Optional[str]

The unique identifier of the user account associated with this representative, if applicable.

formatuuid

Metadata about the API request, including an identifier and timestamp.

api_request_id: str

Unique identifier for this API request, useful for troubleshooting.

formatuuid
api_request_timestamp: datetime

Timestamp for this API request, useful for troubleshooting.

formatdate-time
response_type: Literal["object", "array", "error", "none"]

Indicates the structure of the returned content.

  • "object" means the data field contains a single JSON object.
  • "array" means the data field contains an array of objects.
  • "error" means the data field contains an error object with details of the issue.
  • "none" means no data is returned.
One of the following:
"object"
"array"
"error"
"none"
class RepresentativePaged: …
data: List[Data]
id: str

Unique identifier for the representative.

formatuuid
account_id: str

The unique identifier of the account this representative is associated with.

formatuuid
created_at: datetime

Timestamp of when the representative was created.

formatdate-time
dob: date

The date of birth of the representative, in ISO 8601 format (YYYY-MM-DD).

formatdate
email: Optional[str]

The email address of the representative.

formatemail
first_name: str

The first name of the representative.

last_name: str

The last name of the representative.

mobile_number: str

The mobile phone number of the representative.

name: str
relationship: DataRelationship
control: bool

Whether the representative has significant responsibility to control, manage, or direct the organization. One representative must be identified under the control prong for each legal entity.

owner: bool

Whether the representative owns any percentage of of the equity interests of the legal entity.

primary: bool

Whether the person is authorized as the primary representative of the account. This is the person chosen by the business to provide information about themselves, general information about the account, and who consented to the services agreement.

There can be only one primary representative for an account at a time.

percent_ownership: Optional[float]

The percentage of ownership the representative has. Required if 'Owner' is true.

formatdouble
title: Optional[str]

The job title of the representative.

ssn_last4: str

The last 4 digits of the representative's Social Security Number.

status: Literal["created", "onboarding", "active", 2 more]

The current status of the representative.

One of the following:
"created"
"onboarding"
"active"
"rejected"
"inactive"
status_detail: DataStatusDetail
code: str

A machine-readable code for the specific status, useful for programmatic handling.

message: str

A human-readable message describing the current status.

reason: Literal["unverified", "in_review", "pending", 5 more]

A machine-readable identifier for the specific status, useful for programmatic handling.

One of the following:
"unverified"
"in_review"
"pending"
"stuck"
"verified"
"failed_verification"
"disabled"
"new"
source: Literal["watchtower"]

Identifies the origin of the status change (e.g., watchtower). This helps in tracking the cause of status updates.

updated_at: datetime

Timestamp of the most recent update to the representative.

formatdate-time
external_id: Optional[str]

Unique identifier for the representative in your database, used for cross-referencing between Straddle and your systems.

metadata: Optional[Dict[str, str]]

Up to 20 additional user-defined key-value pairs. Useful for storing additional information about the represetative in a structured format.

phone: Optional[str]
user_id: Optional[str]

The unique identifier of the user account associated with this representative, if applicable.

formatuuid

Metadata about the API request, including an identifier, timestamp, and pagination details.

api_request_id: str

Unique identifier for this API request, useful for troubleshooting.

formatuuid
api_request_timestamp: datetime

Timestamp for this API request, useful for troubleshooting.

formatdate-time
max_page_size: int

Maximum allowed page size for this endpoint.

formatint32
page_number: int

Page number for paginated results.

formatint32
page_size: int

Number of items per page in this response.

formatint32
sort_by: str

The field that the results were sorted by.

sort_order: Literal["asc", "desc"]
One of the following:
"asc"
"desc"
total_items: int

Total number of items returned in this response.

formatint32
total_pages: int

The number of pages available.

formatint32
response_type: Literal["object", "array", "error", "none"]

Indicates the structure of the returned content.

  • "object" means the data field contains a single JSON object.
  • "array" means the data field contains an array of objects.
  • "error" means the data field contains an error object with details of the issue.
  • "none" means no data is returned.
One of the following:
"object"
"array"
"error"
"none"