Finix Identities API
{'$ref': 'api-descriptions/tags/identities.md'}
OpenAPI Specification
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:
parameters:
QueryCreatedAtLteFilter:
description: Filter where `created_at` is before the given date.
in: query
name: created_at.lte
schema:
type: string
example: '2022-09-27T11:21:23'
style: form
QueryTitle:
name: title
in: query
required: false
schema:
type: string
example: ceo
description: Filter by the title if available.
QueryLimit:
description: The numbers of items to return.
example: 10
in: query
name: limit
schema:
type: integer
style: form
QueryBusinessType:
name: business_type
in: query
required: false
schema:
type: string
description: Filter by the business type. Partial business types are not supported.
TagsValue:
name: tags.value
in: query
required: false
schema:
type: string
description: Filter by the [value of a `Tag`](https://finix.com/docs/api/overview/#section/Tags).
QueryDefaultStatementDescriptorFilter:
description: Filter by the `default_statement_descriptor`.
in: query
name: default_statement_descriptor
schema:
type: string
style: form
QueryAfterCursor:
name: after_cursor
in: query
required: false
schema:
type: string
description: Return every resource created after the cursor value.
QueryCreatedAtGteFilter:
description: Filter where `created_at` is after the given date.
in: query
name: created_at.gte
schema:
type: string
example: '2022-09-27T11:21:23'
style: form
QueryEmail:
name: email
in: query
required: false
schema:
type: string
example: user@example.org
description: Filter by the email address or email domain. Partial emails are not supported.
QueryFirstName:
name: first_name
in: query
required: false
schema:
type: string
example: Daphne
description: Filter by the first name of the person associated to the `Identity`.
QueryBusinessName:
name: business_name
in: query
required: false
schema:
type: string
description: Filter by the full business name. Partial business names are not supported.
QueryBeforeCursor:
name: before_cursor
in: query
required: false
schema:
type: string
description: Return every resource created before the cursor value.
QueryIdFilter:
description: Filter by `id`.
in: query
name: id
schema:
type: string
style: form
QueryLastName:
name: last_name
in: query
required: false
schema:
type: string
example: kline
description: Filter by the last name of the person associated to the `Identity`.
TagsKey:
name: tags.key
in: query
required: false
schema:
type: string
description: Filter by the [`key` of a `Tag`](/api/overview/#section/Tags).
headers:
x-request-id:
description: A unique ID for this specific API request attempt.
schema:
type: string
date:
schema:
type: string
finix-apiuser-role:
schema:
type: string
enum:
- ROLE_ADMIN
- ROLE_PLATFORM
- ROLE_PARTNER
- ROLE_MERCHANT
schemas:
ErrorGeneric:
type: object
properties:
total:
type: integer
_embedded:
type: object
properties:
errors:
type: array
items:
type: object
additionalProperties: true
properties:
code:
type: string
enum:
- FORBIDDEN
logref:
$ref: '#/components/schemas/LogRef'
message:
type: string
_links:
type: object
properties:
source:
type: object
properties:
href:
type: string
Error403ForbiddenList:
type: object
properties:
total:
type: integer
_embedded:
type: object
properties:
errors:
type: array
items:
type: object
additionalProperties: true
properties:
code:
type: string
enum:
- FORBIDDEN
logref:
$ref: '#/components/schemas/LogRef'
message:
type: string
_links:
type: object
properties:
source:
type: object
properties:
href:
type: string
description: ''
title: ''
UpdatedAt:
type: string
title: UpdatedAt
format: date-time
description: Timestamp of when the object was last updated.
PageCursor:
title: PageCursor
x-stoplight:
id: 8v9on8n2939z2
type: object
properties:
limit:
type: integer
description: The number of entries to return.
next_cursor:
type: string
description: The cursor to use for the next page of results.
nullable: true
description: Details the page that's returned.
Identity:
description: ''
x-examples:
example-1:
id: IDpYDM7J9n57q849o9E9yNrG
application: APgPDQrLD52TYvqazjHJJchM
entity:
title: CEO
first_name: dwayne
last_name: Sunkhronos
email: user@example.org
business_name: Petes Coffee
business_type: INDIVIDUAL_SOLE_PROPRIETORSHIP
doing_business_as: Petes Coffee
phone: '14158885080'
business_phone: +1 (408) 756-4497
personal_address:
line1: 741 Douglass St
line2: Apartment 7
city: San Mateo
region: CA
postal_code: '94114'
country: USA
business_address:
line1: 741 Douglass St
line2: Apartment 8
city: San Mateo
region: CA
postal_code: '94114'
country: USA
mcc: '4900'
dob:
day: 27
month: 6
year: 1978
max_transaction_amount: 12000000
amex_mid: null
discover_mid: null
url: www.PetesCoffee.com
annual_card_volume: 12000000
has_accepted_credit_cards_previously: true
incorporation_date:
day: 27
month: 6
year: 1978
principal_percentage_ownership: 50
short_business_name: null
ownership_type: PRIVATE
tax_authority: null
tax_id_provided: true
business_tax_id_provided: true
default_statement_descriptor: Petes Coffee
tags:
Studio Rating: '4.7'
created_at: '2022-01-27T07:36:52.11Z'
updated_at: '2022-01-27T07:36:52.00Z'
additional_underwriting_data:
annual_ach_volume: 200000
average_ach_transfer_amount: 200000
average_card_transfer_amount: 200000
business_description: SB3 vegan cafe
card_volume_distribution:
card_present_percentage: 30
ecommerce_percentage: 60
mail_order_telephone_order_percentage: 10
credit_check_allowed: true
credit_check_ip_address: 42.1.1.113
credit_check_timestamp: '2021-04-28T16:42:55Z'
credit_check_user_agent: Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)
merchant_agreement_accepted: true
merchant_agreement_ip_address: 42.1.1.113
merchant_agreement_timestamp: '2021-04-28T16:42:55Z'
merchant_agreement_user_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)
refund_policy: MERCHANDISE_EXCHANGE_ONLY
volume_distribution_by_business_type:
business_to_business_volume_percentage: 100
business_to_consumer_volume_percentage: 0
consumer_to_consumer_volume_percentage: 0
other_volume_percentage: 0
person_to_person_volume_percentage: 0
_links:
self:
href: https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG
verifications:
href: https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/verifications
merchants:
href: https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/merchants
settlements:
href: https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/settlements
authorizations:
href: https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/authorizations
transfers:
href: https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/transfers
payment_instruments:
href: https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/payment_instruments
associated_identities:
href: https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/associated_identities
disputes:
href: https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/disputes
application:
href: https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM
title: ''
type: object
properties:
id:
type: string
minLength: 1
description: The ID of the `Identity` resource.
created_at:
$ref: '#/components/schemas/CreatedAt'
updated_at:
$ref: '#/components/schemas/UpdatedAt'
additional_underwriting_data:
type: object
description: Additional underwriting data that's required to verify the `Identity`.
nullable: true
properties:
annual_ach_volume:
type: integer
description: The approximate annual ACH sales expected to be processed (in cents) by this seller (max 10 characters).
average_ach_transfer_amount:
type: integer
description: The approximate average ACH sale amount (in cents) for this seller.
average_card_transfer_amount:
type: integer
description: The average credit card sale amount (in cents) for this seller.
business_description:
type: string
minLength: 1
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.
nullable: true
properties:
card_present_percentage:
type: integer
description: The percentage of the merchant's volume that's card present (between 0 and 100).
ecommerce_percentage:
type: integer
description: The percentage of the merchant's business that is eCommerce (between 0 and 100).
mail_order_telephone_order_percentage:
type: integer
description: The percentage of the merchant's business that is a mail or telephone order (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
minLength: 1
description: The IP address of the merchant when they consented to a credit check (e.g., 42.1.1.113 ).
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
minLength: 1
description: IP address of the merchant when this merchant accepted the merchant agreement (e.g., 42.1.1.113).
merchant_agreement_timestamp:
type: string
minLength: 1
description: Timestamp of when the merchant accepted Finix's Terms of Service (e.g., 2021-04-28T16:42:55Z).
merchant_agreement_user_agent:
type: string
minLength: 1
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)).
refund_policy:
type: string
minLength: 1
description: Include the value that best applies to the seller's refund policy.
enum:
- NO_REFUNDS
- MERCHANDISE_EXCHANGE_ONLY
- WITHIN_30_DAYS
- OTHER
volume_distribution_by_business_type:
type: object
description: Merchant's distribution of credit card volume by business type. Sum of `volume_distribution_by_business_type` must be 100.
nullable: true
properties:
business_to_business_volume_percentage:
type: integer
description: The percentage of the merchant's volume that's business to business (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).
consumer_to_consumer_volume_percentage:
type: integer
description: Merchant's percentage of volume that is consumer to consumer (between 0 and 100).
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).
person_to_person_volume_percentage:
type: integer
description: The percentage the merchant's volume that's person to person (between 0 and 100).
application:
type: string
minLength: 1
description: ID of the `Application` associated with the `Identity`.
entity:
type: object
description: The underwriting details required to verify the `Identity`.
properties:
amex_mid:
type: integer
description: Assigned amexMid value. If a value is passed, it must be 10 or 11 digits.
nullable: true
annual_card_volume:
type: integer
description: The annual credit card sales (in cents) expected to be processed by this merchant (max 19 characters).
nullable: true
business_address:
type: object
description: The primary address for the legal entity.
nullable: true
properties:
line1:
type: string
minLength: 1
description: First line of the address (max 35 characters).
nullable: true
line2:
type: string
minLength: 1
description: Second line of the address (max 35 characters).
nullable: true
city:
type: string
minLength: 1
description: City (max 20 characters).
nullable: true
region:
type: string
minLength: 1
description: 2-letter state code.
nullable: true
postal_code:
type: string
minLength: 1
description: Zip or Postal code (max 7 characters).
nullable: true
country:
type: string
minLength: 1
description: 3-Letter Country code (e.g. USA).
nullable: true
business_name:
type: string
minLength: 1
description: The merchant's legal business name (max 120 characters).<ul><li>If <strong>INDIVIDUAL_SOLE_PROPRIETORSHIP</strong>, pass the owner's legal first name, last name and middle initial.
nullable: true
business_phone:
type: string
minLength: 1
description: Customer service phone number where the merchant can be reached (max 10 characters).
nullable: true
business_tax_id_provided:
type: boolean
description: Details if the `business_tax_id` was provided.
business_type:
description: Include the value that best applies to the merchant.
type: string
nullable: true
default_statement_descriptor:
type: string
minLength: 1
description: The description of the merchant that appears on the buyer's bank or card statement.
nullable: true
discover_mid:
description: Assigned discoverMid value.
type: integer
nullable: true
dob:
type: object
description: The control owner's date of birth.
nullable: true
properties:
day:
type: integer
description: Day of birth (between 1 and 31).
minimum: 1
month:
type: integer
description: Month of birth (between 1 and 12).
minimum: 1
year:
type: integer
description: Year of birth (4-digit). Year must be greater than 1900.
minimum: 1900
doing_business_as:
type: string
minLength: 1
description: Alternate names of the business. If there are no other names, pass the same value used for `business_name` (max 60 characters).
nullable: true
email:
type: string
minLength: 1
description: The email address of the principal control owner where they can be reached (max 100 characters).
nullable: true
first_name:
type: string
minLength: 1
description: The legal first name of the merchant's control owner (max 20 characters).
nullable: true
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.
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
minLength: 1
description: The legal last name of the merchant's control owner (max 20 characters).
nullable: true
max_transaction_amount:
type: integer
description: The maximum amount (in cents) that can be charged for a single transaction (max 12 characters).
nullable: true
mcc:
type: string
minLength: 1
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/)
nullable: true
ownership_type:
type: string
minLength: 1
description: 'Values can be either: <ul><li><strong>PUBLIC</strong> to indicate a publicly-traded company.<li><strong>PRIVATE</strong> for privately-held businesses.'
enum:
- PUBLIC
- PRIVATE
nullable: true
personal_address:
type: object
description: The home address of the merchant's principal control owner. This field is used for identity verification purposes.
nullable: true
properties:
line1:
type: string
minLength: 1
description: First line of the address (max 35 characters).
nullable: true
line2:
type: string
minLength: 1
description: Second line of the address (max 35 characters).
nullable: true
city:
type: string
minLength: 1
description: City (max 20 characters).
nullable: true
region:
type: string
minLength: 1
description: 2-letter State code.
nullable: true
postal_code:
type: string
minLength: 1
description: Zip or Postal code (max 7 characters).
nullable: true
country:
type: string
minLength: 1
description: 3-Letter country code (e.g. USA).
# --- truncated at 32 KB (97 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/finix/refs/heads/main/openapi/finix-identities-api-openapi.yml