openapi: 3.0.2 info: title: Finix Authorizations Identities API description: $ref: api-descriptions/main.md contact: name: Finix url: https://finix.com email: support@finixpayments.com version: '2022-02-01' servers: - description: Sandbox server to be used for testing and development url: https://finix.sandbox-payments-api.com security: - BasicAuth: [] tags: - name: Identities description: $ref: api-descriptions/tags/identities.md paths: /identities: post: tags: - Identities description: "Create an `Identity` for your seller or buyer.\n\nAll fields for a buyer's `Identity` are optional. \n\nProviding `business_type` indicates that the `Identity` is being created for a Merchant.\n\nRelated Guides: [Getting Started](/guides/getting-started/), [Onboarding](/guides/onboarding/)" summary: Create an Identity operationId: createIdentity requestBody: $ref: '#/components/requestBodies/CreateIdentityRequest' responses: '201': $ref: '#/components/responses/Identity' '400': $ref: '#/components/responses/ErrorUnprocessableEntity' '401': $ref: '#/components/responses/ErrorUnauthorized' '403': $ref: '#/components/responses/ErrorForbidden403' '406': $ref: '#/components/responses/Error406NotAcceptable' x-java-method-name: create parameters: - schema: type: string default: '2018-01-01' example: '2022-02-01' in: header name: Finix-Version description: Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/) x-python-method-name: create get: tags: - Identities description: Retrieve a list of `Identities`. summary: List Identities operationId: listIdentities parameters: - $ref: '#/components/parameters/QueryAfterCursor' - $ref: '#/components/parameters/QueryLimit' - $ref: '#/components/parameters/QueryIdFilter' - $ref: '#/components/parameters/QueryCreatedAtGteFilter' - $ref: '#/components/parameters/QueryCreatedAtLteFilter' - $ref: '#/components/parameters/QueryDefaultStatementDescriptorFilter' - $ref: '#/components/parameters/QueryBusinessName' - $ref: '#/components/parameters/QueryBusinessType' - $ref: '#/components/parameters/QueryEmail' - $ref: '#/components/parameters/QueryFirstName' - $ref: '#/components/parameters/QueryLastName' - $ref: '#/components/parameters/QueryTitle' - $ref: '#/components/parameters/QueryBeforeCursor' - $ref: '#/components/parameters/TagsKey' - $ref: '#/components/parameters/TagsValue' responses: '200': $ref: '#/components/responses/IdentitiesList' '401': $ref: '#/components/responses/ErrorUnauthorized' '403': $ref: '#/components/responses/ErrorForbidden403' '404': $ref: '#/components/responses/ErrorNotFound' '406': $ref: '#/components/responses/Error406NotAcceptable' x-java-method-name: list x-group-parameters: true x-codeSamples: - lang: cURL label: curl source: "curl \"https://finix.sandbox-payments-api.com/identities\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Finix-Version: 2022-02-01\" \\\n -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e\n" x-python-method-name: list x-returns-list: true /identities/{identity_id}: parameters: - description: ID of the `Identity` to fetch. required: true in: path name: identity_id schema: type: string get: tags: - Identities description: Retrieve the details of a previously created `Identity`. summary: Fetch an Identity operationId: getIdentity responses: '200': $ref: '#/components/responses/Identity' '401': $ref: '#/components/responses/ErrorUnauthorized' '403': $ref: '#/components/responses/ErrorForbidden403' '404': $ref: '#/components/responses/ErrorNotFound' '406': $ref: '#/components/responses/Error406NotAcceptable' x-java-method-name: get x-codeSamples: - lang: cURL label: curl source: "curl \"https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K\" \\\n -H \"Finix-Version: 2022-02-01\" \\\n -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e\n" x-python-method-name: get put: tags: - Identities description: 'Update an existing `Identity`. If you are updating the `Identity` of a `Merchant` that’s already been onboarded, you need to [verify the merchant again](/api/tag/Merchants/#tag/Merchants/operation/createMerchantVerification).' summary: Update an Identity operationId: updateIdentity requestBody: $ref: '#/components/requestBodies/UpdateIdentityRequest' responses: '200': $ref: '#/components/responses/Identity' '400': $ref: '#/components/responses/ErrorUnprocessableEntity' '401': $ref: '#/components/responses/ErrorUnauthorized' '403': $ref: '#/components/responses/ErrorForbidden403' '404': $ref: '#/components/responses/ErrorNotFound' '406': $ref: '#/components/responses/Error406NotAcceptable' x-java-method-name: update x-codeSamples: - lang: cURL label: curl source: $ref: xcode/curl/identities/updateidentity.md x-python-method-name: update /identities/{identity_id}/associated_identities: parameters: - description: ID of `Identity` to associate object with. required: true in: path name: identity_id schema: type: string post: tags: - Identities description: Create an associated `Identity` for [every owner with 25% or more ownership](/guides/onboarding/onboarding-with-api#step-3-add-associated-identities) over the merchant. summary: Create an Associated Identity operationId: createAssociatedIdentity requestBody: $ref: '#/components/requestBodies/CreateAssociatedIdentityRequest' responses: '201': $ref: '#/components/responses/Identity' '400': $ref: '#/components/responses/ErrorUnprocessableEntity' '401': $ref: '#/components/responses/ErrorUnauthorized' '403': $ref: '#/components/responses/ErrorForbidden403' '404': $ref: '#/components/responses/ErrorNotFound' '406': $ref: '#/components/responses/Error406NotAcceptable' x-java-method-name: createAssociatedIdentity x-codeSamples: - lang: cURL label: curl source: "curl \"https://finix.sandbox-payments-api.com/identities/IDgXNAaoy5d4TLkp5ze6gScA/associated_identities\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Finix-Version: 2022-02-01\" \\\n -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e\n -d '\n{\n \"entity\": {\n \"first_name\": \"John\", \n \"last_name\": \"Smith\", \n \"title\": \"Founder\", \n \"dob\": {\n \"month\": 1, \n \"day\": 1, \n \"year\": 2013\n }, \n \"principal_percentage_ownership\": 25, \n \"phone\": \"14158885080\", \n \"personal_address\": {\n \"city\": \"San Francisco\", \n \"region\": \"CA\", \n \"postal_code\": \"90650\", \n \"line1\": \"123 Main Street\", \n \"country\": \"USA\"\n }, \n \"email\": \"john.smith@company1.com\", \n \"tax_id\": \"123456789\"\n }\n}'\n" x-python-method-name: create_associated_identity get: tags: - Identities description: Retrieve a list of `Associated Identities` for an `Identity`. summary: List Associated Identities operationId: listIdentityAssociatedIdentities parameters: - required: false in: query name: limit schema: type: integer format: int64 description: The number of entries to return. - $ref: '#/components/parameters/QueryAfterCursor' - $ref: '#/components/parameters/QueryBeforeCursor' responses: '200': $ref: '#/components/responses/IdentitiesList' '401': $ref: '#/components/responses/ErrorUnauthorized' '403': $ref: '#/components/responses/ErrorForbidden403' '404': $ref: '#/components/responses/ErrorNotFound' '406': $ref: '#/components/responses/Error406NotAcceptable' x-java-method-name: listAssociatedIdentities x-group-parameters: true x-codeSamples: - lang: cURL label: curl source: "curl \"https://finix.sandbox-payments-api.com/identities/IDf33pdVaTZGXVFNccdKvaPu/associated_identities\" \\\n -H \"Finix-Version: 2022-02-01\" \\\n -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e\n" x-python-method-name: list_associated_identities x-returns-list: true components: schemas: Error406NotAcceptable: type: object properties: total: type: integer _embedded: type: object properties: errors: type: array items: type: object additionalProperties: true properties: code: type: string enum: - NOT_FOUND logref: $ref: '#/components/schemas/LogRef' message: type: string _links: type: object properties: source: type: object properties: href: type: string title: '' IdentitiesList: type: object properties: page: $ref: '#/components/schemas/PageCursor' _embedded: type: object description: List of `Identity` resources. properties: identities: type: array uniqueItems: true description: An `Identity` resource represents either a person or business in Finix. items: $ref: '#/components/schemas/Identity' _links: $ref: '#/components/schemas/ListLinks' CreateIdentityRequest: type: object properties: additional_underwriting_data: type: object description: "- Additional underwriting details required to verify `Identities`. \n- Required for any `Merchants` onboarded by Finix Flex customers. If you have any questions, please contact [Finix Support](/guides/business/support-at-finix/)." nullable: true properties: annual_ach_volume: type: integer description: The approximate annual ACH sales expected to be processed (in cents) by this merchant (max 10 characters). average_ach_transfer_amount: type: integer description: The approximate average ACH sale amount (in cents) for this merchant. average_card_transfer_amount: type: integer description: The average credit card sale amount (in cents) for this merchant. business_description: type: string description: Description of this merchant's business (max 200 characters). card_volume_distribution: type: object description: The distribution of the merchant's credit card volume The sum of `card_volume_distribution` must be 100. properties: card_present_percentage: type: integer description: The percentage of the merchant's volume that's card present (between 0 and 100). mail_order_telephone_order_percentage: type: integer description: The percentage of the merchant's business that is a mail order or telephone order (between 0 and 100). ecommerce_percentage: type: integer description: The percentage of the merchant's business that is eCommerce (between 0 and 100). credit_check_allowed: type: boolean description: Sets if this merchant has consented and accepted to a credit check. credit_check_ip_address: type: string description: The IP address of the merchant when they consented to a credit check (e.g., 42.1.1.113 ). minLength: 1 credit_check_timestamp: type: string minLength: 1 description: A timestamp of when this merchant consented to a credit check (e.g., 2021-04-28T16:42:55Z). credit_check_user_agent: type: string minLength: 1 description: The details of the browser that was used when this merchant consented to a credit check (e.g., Mozilla 5.0 (Macintosh; Intel Mac OS X 10 _14_6)). merchant_agreement_accepted: type: boolean description: Sets whether this merchant has accepted the terms and conditions of the merchant agreement. merchant_agreement_ip_address: type: string description: IP address of the merchant when this merchant accepted the merchant agreement (e.g., 42.1.1.113). minLength: 1 merchant_agreement_timestamp: type: string minLength: 1 description: Sets if this merchant has consented and accepted to a credit check. merchant_agreement_user_agent: type: string description: The details of the browser that was used when this merchant accepted Finix's Terms of Service (e.g., Mozilla 5.0 (Macintosh; Intel Mac OS X 10 _14_6)). minLength: 1 refund_policy: type: string description: The details of the browser that was used when this merchant consented to a credit check (e.g., Mozilla 5.0 (Macintosh; Intel Mac OS X 10 _14_6)). enum: - NO_REFUNDS - MERCHANDISE_EXCHANGE_ONLY - 30_DAYS - OTHER volume_distribution_by_business_type: type: object description: IP address of the merchant when this merchant accepted the merchant agreement (e.g., 42.1.1.113). properties: other_volume_percentage: type: integer description: The percentage of the merchant's volume that isn't represented by the previous fields (between 0 and 100). consumer_to_consumer_volume_percentage: type: integer description: Merchant's percentage of volume that is consumer to consumer (between 0 and 100). business_to_consumer_volume_percentage: type: integer description: The percentage of the merchant's volume that's business to consumer (between 0 and 100). business_to_business_volume_percentage: type: integer description: The percentage of the merchant's volume that's business to business (between 0 and 100). person_to_person_volume_percentage: type: integer description: The percentage of the merchant's volume that's person to person (between 0 and 100). entity: type: object description: The underwriting details required to verify `Identities`. properties: annual_card_volume: type: integer description: The annual credit card sales (in cents) expected to be processed (max 19 characters). business_address: type: object description: The primary address for the legal entity. required: - city - country - region - line1 - postal_code nullable: true properties: city: type: string minLength: 1 description: City (max 20 characters). country: type: string minLength: 1 description: 3-Letter Country code (e.g. USA). region: type: string minLength: 1 description: 2-letter state code. line2: type: string minLength: 1 description: Second line of the address (max 35 characters). line1: type: string minLength: 1 description: First line of the address (max 35 characters). postal_code: type: string minLength: 1 description: Zip or Postal code (max 7 characters). business_name: type: string description: The merchant's legal business name (max 120 characters). nullable: true business_phone: type: string description: Customer service phone number where the merchant can be reached (max 10 characters). business_tax_id: type: string description: Nine digit Tax Identification Number (TIN), Employer Identification Number (EIN). If the `business_type` is **INDIVIDUAL\_SOLE\_PROPRIETORSHIP** and they do not have an EIN, use the sole proprietor's Social Security Number (SSN). business_type: type: string description: The business entity type of the Merchant. enum: - INDIVIDUAL_SOLE_PROPRIETORSHIP - CORPORATION - LIMITED_LIABILITY_COMPANY - PARTNERSHIP - ASSOCIATION_ESTATE_TRUST - TAX_EXEMPT_ORGANIZATION - INTERNATIONAL_ORGANIZATION - GOVERNMENT_AGENCY default_statement_descriptor: type: string description: The description of the merchant that appears on the buyer's bank or card statement. dob: type: object description: The control owner's date of birth. required: - day - month - year properties: day: type: integer description: Day of birth (between 1 and 31). month: type: integer description: Month of birth (between 1 and 12). year: type: integer description: Year of birth (4-digit). Year must be greater than 1900 doing_business_as: type: string description: Alternate names of the business. If there are no other names, pass the same value used for `business_name` (max 60 characters). email: type: string description: The email address of the buyer where they can be reached (max 100 characters). first_name: type: string description: The legal first name of the buyer (max 20 characters). has_accepted_credit_cards_previously: type: boolean description: Defaults to **false** if not passed. incorporation_date: type: object description: The date the company was founded and registered. required: - day - month - year nullable: true properties: day: type: integer description: Day business was incorporated (between 1 and 31). month: type: integer description: Month business was incorporated (between 1 and 12). year: type: integer description: Year business was incorporated (4-digit). last_name: type: string description: The legal last name of the buyer (max 20 characters). max_transaction_amount: type: integer description: The maximum amount (in cents) that can be charged for a single transaction (max 12 characters). ach_max_transaction_amount: type: integer description: The maximum amount (in cents) that can be charged for a single ACH transaction (max 12 characters). mcc: type: string description: The Merchant Category Code ([MCC](http://www.dm.usda.gov/procurement/card/card\_x/mcc.pdf)) that this merchant will be classified under. For a list of approved MCCs, see [Approved Merchant Category Codes.](/docs/guides/business/security-and-compliance/approved-merchants/) ownership_type: type: string description: "Avalible values include: