> ## Documentation Index > Fetch the complete documentation index at: https://docs.lead.bank/llms.txt > Use this file to discover all available pages before exploring further. # Batch Create User Account Entity Relationships > Add Entities to a User Account under a single relationship type. ## OpenAPI ````yaml POST /v2/user_accounts/{user_account_id}/entity_relationships/batch openapi: 3.0.1 info: title: Lead Bank description: Lead Bank's APIs version: v1.0 servers: - url: https://api.sandbox.lead.bank - url: https://api.lead.bank security: - bearerAuth: [] tags: - name: ACH - name: Account Number - name: OAuth - name: Events - name: Instant Payments - name: Lending - name: Simulation - name: Internal Transfer - name: Disbursement - name: Entity - name: Wire - name: Originator - name: Funding - name: Receivable Sale - name: Balances - name: Compliance - name: Application - name: User Account - name: Blockchain Payment - name: Core Account - name: Core Balance - name: Core Transaction - name: Event Subscription - name: Receivable - name: User Credit Transaction - name: Files paths: /v2/user_accounts/{user_account_id}/entity_relationships/batch: post: tags: - User Account summary: Batch create user account entity relationships description: Add Entities to a User Account under a single relationship type. operationId: batch-create-user-account-entity-relationships-v2 parameters: - name: user_account_id in: path required: true description: User Account ID schema: $ref: '#/components/schemas/UserAccountID' - name: Idempotency-Key in: header description: >- A unique key for this request, up to 255 characters. Retrying with the same key and body returns the original response without creating the relationships twice. See [Idempotency](https://docs.lead.bank/api-reference/using-the-api/idempotency-v2). required: true schema: type: string maxLength: 255 example: 3f1c9a52-7d4e-4b8a-9c21-6e0f5d2a8b14 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchCreateEntityRelationshipsRequest' examples: authorized_user: summary: Batch add authorized users value: entity_ids: - entity_8kL9jH7gF6dS5aQ4wE3rT2yU1iO - entity_2mN3bV4cX5zL6kwdJ7hG8fD9sA0 - entity_1qW2eR3tY4uI5oP6aS7dF8gH9jK - entity_9pLuO8iK7yJ6hT5gR4fE3dD2sS1 - entity_5zX4cV3bN2m1qW0eR9tY8uI7oP6 relationship_type: authorized_user responses: '200': description: Entity relationships created successfully. content: application/json: schema: type: object properties: user_account_id: $ref: '#/components/schemas/UserAccountID' relationship_type: $ref: '#/components/schemas/EntityRelationshipType' entity_ids: type: array description: >- List of entity IDs associated with the user account under the specified relationship type. items: $ref: '#/components/schemas/EntityID' required: - user_account_id - relationship_type - entity_ids examples: authorized_user: summary: Batch add authorized users value: user_account_id: user_account_9h8g7f6e5d4c3b2a1z0y9x8w7v6 relationship_type: authorized_user entity_ids: - entity_8kL9jH7gF6dS5aQ4wE3rT2yU1iO - entity_2mN3bV4cX5zL6kwdJ7hG8fD9sA0 - entity_1qW2eR3tY4uI5oP6aS7dF8gH9jK - entity_9pLuO8iK7yJ6hT5gR4fE3dD2sS1 - entity_5zX4cV3bN2m1qW0eR9tY8uI7oP6 '400': description: >- The request could not be parsed (`request_malformed`), or the `Idempotency-Key` header is missing (`idempotency_key_missing`). content: application/json: schema: $ref: '#/components/schemas/Error' example: code: request_malformed message: The request is invalid and cannot be parsed by the server. errors: - code: body_malformed message: The request body is missing or isn't a JSON object. '403': description: >- `code` is one of: `authentication_missing` (the request has no credentials), `token_invalid` (the bearer token is missing, expired, or invalid, or does not grant `user_account/read_write`), `source_ip_not_allowed` (the request came from an IP address that is not on your program's allowlist). content: application/json: schema: $ref: '#/components/schemas/Error' example: code: token_invalid message: The bearer token is missing, expired, malformed, or invalid. '404': description: >- No user account exists with this ID, or it is not visible to your program. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: object_not_found message: >- No object exists at the requested ID, or it is not visible to this caller. '409': description: >- A concurrent request with the same `Idempotency-Key` is still in flight. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: idempotency_key_in_use message: >- A concurrent request using this Idempotency-Key is still in flight. '422': description: >- The request was parsed but cannot be processed. `code` is one of: `parameters_invalid` (`relationship_type` or `entity_ids` is missing or invalid; an entity appears twice (`parameter_duplicated`); or the relationship type would exceed 20 entities (`parameter_bound_exceeded`). All failures are returned at once), `related_object_invalid` (an entity does not exist or belongs to another program; `errors[].code` is `reference_not_found`, with the path in `parameters`), `related_object_not_ready` (an entity is not eligible for the relationship type (`entity_role_missing`), with the entity's path in `parameters`; update the entity, then retry the request unchanged), `related_object_conflict` (adding the entities would mix consumer and commercial account holders (`account_holder_types_mismatched`), or an account holder is a lead or partner entity), `lead_control_restricted` (your program is not enabled for User Accounts v2; `errors[].code` is `feature_not_enabled`), `idempotency_request_inconsistent` (this `Idempotency-Key` was used with a different request body). content: application/json: schema: $ref: '#/components/schemas/Error' example: code: related_object_invalid message: >- An object referenced in the request doesn't exist or can't be used. errors: - code: reference_not_found message: Entity entity_8kL9jH7gF6dS5aQ4wE3rT2yU1iO does not exist. parameters: - entity_ids[0] '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: rate_limit_exceeded message: >- You have exceeded the rate limit for this endpoint. Retry with backoff. '500': description: Internal server error. Retry with the same `Idempotency-Key`. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: internal_server_error message: >- Something went wrong on our end. Contact Lead with the Request-Id if this persists. '503': description: >- The service or endpoint is temporarily unavailable. Retry after a delay. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: service_unavailable message: >- The service is temporarily unavailable. Retry after the indicated delay. '504': description: >- An upstream system did not respond in time. Retry with backoff, and with the same `Idempotency-Key` on a `POST` or `PATCH`. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: gateway_timeout message: An upstream system timed out. Retry with backoff. components: schemas: UserAccountID: type: string description: The ID of the User Account object. example: user_account_xyz123 pattern: ^user_account_\w+$ BatchCreateEntityRelationshipsRequest: type: object description: Request body for batch creating entity relationships on an account. properties: entity_ids: type: array description: >- List of entity IDs to associate with the account under the specified relationship type. maxItems: 20 items: $ref: '#/components/schemas/EntityID' relationship_type: $ref: '#/components/schemas/EntityRelationshipType' required: - entity_ids - relationship_type EntityRelationshipType: type: string description: Indicates the type of Entity enum: - account_holder - authorized_signer - authorized_user example: account_holder EntityID: type: string description: The ID of your entity. example: entity_xyz123 pattern: ^entity_[^\s]{1,33}$ Error: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: >- A human-readable description of the error family. Identical for every occurrence of a given `code`; carries no request-specific detail. example: One or more parameters are invalid. errors: type: array description: >- Zero or more specific errors within this family. Always present for validation errors, one entry per failing field. items: $ref: '#/components/schemas/ErrorItem' ErrorCode: type: string description: >- A snake_case code identifying the error family — the stable, machine-readable value partners branch on, together with the HTTP status. example: parameters_invalid enum: - request_malformed - content_too_large - idempotency_key_missing - authentication_missing - token_invalid - source_ip_not_allowed - url_invalid - object_not_found - method_not_allowed - idempotency_key_in_use - idempotency_request_inconsistent - rate_limit_exceeded - internal_server_error - service_unavailable - endpoint_disabled - gateway_timeout - unclassified - parameters_invalid - related_object_invalid - related_object_not_ready - related_object_conflict - limit_exceeded - client_control_restricted - lead_control_restricted - object_state_conflict - object_modified_concurrently - operation_invalid ErrorItem: type: object required: - code - message properties: code: type: string description: A snake_case code naming the specific error or sub-category. example: required message: type: string description: >- A human-readable description of this specific error, with interpolated values where relevant. example: account_number_id is required. parameters: type: array description: >- The request fields this error implicates, in dot notation for nested fields. Present for validation errors. items: type: string example: - account_number_id securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.