> ## Documentation Index > Fetch the complete documentation index at: https://developer.finogates.com/llms.txt > Use this file to discover all available pages before exploring further. # Add an Address to a Payee > Save an address for a payee. A payee can hold more than one per destination country. `country` (ISO 3166-1 alpha-2, e.g. `MX`, `IN`, `AE`) is required. When you send an international payout you reference the address by its ID; its country must match the payout's destination country and it must carry every field that corridor requires, or the payout is rejected. `purposes` is also required — one or more product keys naming what this address may be used for. Fetch the keys your platform can use from `GET /v1/platform/payees/address-purposes`. Only one live address per country may carry the `international` purpose. Adding a second one for a country that already has one returns `409 international_address_conflict`, naming the existing address's ID. Resubmit with `on_international_conflict` set to `replace` (the existing address loses the `international` purpose, or is revoked outright if that was its only one) or `keep` (the existing address is untouched and `international` is dropped from this one — it must have at least one other purpose, or the request is rejected). ## OpenAPI ````yaml POST /v1/platform/payees/addresses/{payee_id} openapi: 3.1.0 info: title: Finogate Platform API v1 version: 0.1.0 servers: - url: https://api-sandbox.finogates.com description: Sandbox - url: https://api.finogates.com description: Production security: [] tags: - name: auth - name: users - name: payees - name: verification - name: bank accounts - name: card processing - name: digital-assets - name: international - name: fees - name: onboarding - name: pending-applications - name: wallets - name: payments - name: document mailing - name: merchant onboarding - name: catalog - name: webhooks - name: screening - name: Platform - File Scanning - name: phone-numbers - name: sms - name: calls - name: listings - name: Card Transfers - name: embed-tokens paths: /v1/platform/payees/addresses/{payee_id}: post: tags: - payees summary: Add an Address to a Payee description: >- Save an address for a payee. A payee can hold more than one — one per destination country — because the recipient's address, phone, and ID document are local to the country the money is sent to. `country` (ISO 3166-1 alpha-2, e.g. `MX`, `IN`, `AE`) is required. When you send an international payout you reference the address by its ID; its country must match the payout's destination country and it must carry every field that corridor requires, or the payout is rejected. operationId: create_address_v1_platform_payees_addresses__payee_id__post parameters: - name: payee_id in: path required: true schema: type: string format: uuid title: Payee Id - name: user_id in: query required: true schema: type: string format: uuid description: The unique ID of the user who owns this payee. examples: - b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4 title: User Id description: The unique ID of the user who owns this payee. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PayeeAddressCreate' examples: mexico: summary: Mexico recipient address + local phone + ID value: label: Home — Guadalajara line1: Av. Vallarta 1234 city: Guadalajara state: Jalisco postal_code: '44100' country: MX phone: '+523312345678' doc_number: GORA850315HJCXYZ01 doc_type: CURP doc_issue_country: MX is_default: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CommonResponse_PayeeAddressRead_' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - _AuthenticatedBearer: [] components: schemas: PayeeAddressCreate: properties: label: anyOf: - type: string maxLength: 120 - type: 'null' title: Label address_type: anyOf: - type: string maxLength: 30 - type: 'null' title: Address Type line1: type: string maxLength: 255 title: Line1 description: Street and number. line2: anyOf: - type: string maxLength: 255 - type: 'null' title: Line2 city: anyOf: - type: string maxLength: 120 - type: 'null' title: City state: anyOf: - type: string maxLength: 120 - type: 'null' title: State postal_code: anyOf: - type: string maxLength: 20 - type: 'null' title: Postal Code phone: anyOf: - type: string maxLength: 40 - type: 'null' title: Phone doc_number: anyOf: - type: string maxLength: 100 - type: 'null' title: Doc Number doc_type: anyOf: - type: string maxLength: 50 - type: 'null' title: Doc Type doc_issue_country: anyOf: - type: string maxLength: 10 - type: 'null' title: Doc Issue Country doc_issue_date: anyOf: - type: string maxLength: 20 - type: 'null' title: Doc Issue Date doc_due_date: anyOf: - type: string maxLength: 20 - type: 'null' title: Doc Due Date doc_issuer: anyOf: - type: string maxLength: 255 - type: 'null' title: Doc Issuer is_default: type: boolean title: Is Default default: false country: type: string title: Country description: ISO 3166-1 alpha-2 country code, e.g. MX, IN, AE. type: object required: - line1 - country title: PayeeAddressCreate description: >- Create a payee address. ``country`` (ISO 3166-1 alpha-2) is required — it is the key an international payout matches against the resolved destination country, so an address with no country could never be used for one. ``line1`` is required too: a saved "address" with no street is not usable for a mailed check or a payout's beneficiary block. CommonResponse_PayeeAddressRead_: properties: status_code: type: integer title: Status Code description: HTTP status code for the response. data: $ref: '#/components/schemas/PayeeAddressRead' description: Payload or error details. query_generated_time: type: integer title: Query Generated Time description: >- UTC timestamp (milliseconds since epoch) when response was generated. type: object required: - status_code - data - query_generated_time title: CommonResponse[PayeeAddressRead] HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError PayeeAddressRead: properties: id: type: string format: uuid title: Id label: anyOf: - type: string - type: 'null' title: Label address_type: anyOf: - type: string - type: 'null' title: Address Type line1: anyOf: - type: string - type: 'null' title: Line1 line2: anyOf: - type: string - type: 'null' title: Line2 city: anyOf: - type: string - type: 'null' title: City state: anyOf: - type: string - type: 'null' title: State postal_code: anyOf: - type: string - type: 'null' title: Postal Code country: anyOf: - type: string - type: 'null' title: Country phone: anyOf: - type: string - type: 'null' title: Phone doc_number: anyOf: - type: string - type: 'null' title: Doc Number doc_type: anyOf: - type: string - type: 'null' title: Doc Type doc_issue_country: anyOf: - type: string - type: 'null' title: Doc Issue Country doc_issue_date: anyOf: - type: string - type: 'null' title: Doc Issue Date doc_due_date: anyOf: - type: string - type: 'null' title: Doc Due Date doc_issuer: anyOf: - type: string - type: 'null' title: Doc Issuer is_default: type: boolean title: Is Default default: false status: type: string title: Status created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At type: object required: - id - status title: PayeeAddressRead description: |- Response shape for a payee address. ``status`` is surfaced as its label (``active`` / ``disabled`` / …) rather than the stored integer. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: _AuthenticatedBearer: type: oauth2 flows: password: scopes: {} tokenUrl: /v1/platform/auth/token ````