POST /identities
GET /identities
GET /identities/{id}
PUT /identities
POST /identities/{id}/associated_identities
GET /identities/{id}/associated_identities
GET /identities/{id}/associated_identities
An Identity
resource represents either a person or business in Finix. You'll create an Identity
to onboard your sellers, and verify the different owners.
Related Guides: Getting Started, Onboarding, Push to Card
Create an Identity
for your seller or buyer.
All fields for a buyer's Identity
are optional.
Providing business_type
indicates that the Identity
is being created for a Merchant.
Related Guides: Getting Started, Onboarding
object or null
| |
object The underwriting details required to verify | |
tags | object or null Include up to 50
(e.g., |
Single Identity object
Error
Authentication information is missing or invalid
Forbidden
Not Acceptable
{- "id": "IDezsbY5qYujV7ecdrn8psrh",
- "created_at": "2022-10-11T00:37:03.02Z",
- "updated_at": "2022-10-11T00:37:03.02Z",
- "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
}
}, - "application": "APgPDQrLD52TYvqazjHJJchM",
- "entity": {
- "amex_mid": null,
- "annual_card_volume": 12000000,
- "business_address": {
- "line1": "741 Douglass St",
- "line2": "Apartment 8",
- "city": "San Mateo",
- "region": "CA",
- "postal_code": "94114",
- "country": "USA"
}, - "business_name": "Finix Flowers",
- "business_phone": "+1 (408) 756-4497",
- "business_tax_id_provided": true,
- "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
- "default_statement_descriptor": "Finix Flowers",
- "discover_mid": null,
- "dob": {
- "day": 27,
- "month": 6,
- "year": 1978
}, - "doing_business_as": "Finix Flowers",
- "email": "user@example.org",
- "first_name": "John",
- "has_accepted_credit_cards_previously": true,
- "incorporation_date": {
- "day": 27,
- "month": 6,
- "year": 1978
}, - "last_name": "Smith",
- "max_transaction_amount": 12000000,
- "mcc": "0742",
- "ownership_type": "PRIVATE",
- "personal_address": {
- "line1": "741 Douglass St",
- "line2": "Apartment 7",
- "city": "San Mateo",
- "region": "CA",
- "postal_code": "94114",
- "country": "USA"
}, - "phone": "1234567890",
- "principal_percentage_ownership": 50,
- "short_business_name": null,
- "tax_authority": null,
- "tax_id_provided": true,
- "title": "CEO",
- "url": "www.Finix.com"
}, - "tags": {
- "Studio Rating": "4.7"
}, - "_links": {
- "verifications": {
}, - "merchants": {
}, - "settlements": {
}, - "authorizations": {
}, - "transfers": {
}, - "payment_instruments": {
}, - "associated_identities": {
}, - "disputes": {
}, - "application": {
}
}
}
Retrieves a list of Identities
.
sort | string Specify key to be used for sorting the collection. |
after_cursor | string Return every resource created after the cursor value. |
limit | integer The numbers of items to return. Example: limit=10 |
id | string Filter by |
created_at.gte | string Filter where Example: created_at.gte=2022-09-27T11:21:23 |
created_at.lte | string Filter where Example: created_at.lte=2022-09-27T11:21:23 |
default_statement_descriptor | string Filter by the |
business_name | string Filter by the full business name. Partial business names are not supported. |
business_type | string Filter by the business type. Partial business types are not supported. |
string Filter by the email address or email domain. Partial emails are not supported. Example: email=user@example.org | |
first_name | string Filter by the first name of the person associated to the Example: first_name=Daphne |
last_name | string Filter by the last name of the person associated to the Example: last_name=kline |
title | string Filter by the title if available. Example: title=ceo |
before_cursor | string Return every resource created before the cursor value. |
tags.key | string Filter by the |
tags.value | string Filter by the value of a |
List of Identity objects
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
curl https://finix.sandbox-payments-api.com/identities \ -H "Content-Type: application/vnd.api+json" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
{- "_embedded": {
- "identities": [
- {
- "id": "IDrNRsZ2miEQcmGHCpo4rBQr",
- "created_at": "2022-08-16T18:44:27.46Z",
- "updated_at": "2022-08-16T18:44:27.46Z",
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "entity": {
- "amex_mid": null,
- "annual_card_volume": 12000000,
- "business_address": {
- "line1": "741 Douglass St",
- "line2": "Apartment 8",
- "city": "San Mateo",
- "region": "CA",
- "postal_code": "94114",
- "country": "USA"
}, - "business_name": "Petes Coffee",
- "business_phone": "+1 (408) 756-4497",
- "business_tax_id_provided": true,
- "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
- "default_statement_descriptor": "Petes Coffee",
- "discover_mid": null,
- "dob": {
- "day": 27,
- "month": 6,
- "year": 1978
}, - "doing_business_as": "Petes Coffee",
- "email": "user@example.org",
- "first_name": "dwayne",
- "has_accepted_credit_cards_previously": true,
- "incorporation_date": {
- "day": 27,
- "month": 6,
- "year": 1978
}, - "last_name": "xbc",
- "max_transaction_amount": 12000000,
- "mcc": "0742",
- "ownership_type": "PRIVATE",
- "personal_address": {
- "line1": "741 Douglass St",
- "line2": "Apartment 7",
- "city": "San Mateo",
- "region": "CA",
- "postal_code": "94114",
- "country": "USA"
}, - "phone": "1234567890",
- "principal_percentage_ownership": 50,
- "short_business_name": null,
- "tax_authority": null,
- "tax_id_provided": true,
- "title": "CEO",
- "url": "www.PetesCoffee.com"
}, - "tags": {
- "test_key_103": "test_val_103"
}, - "_links": {
- "verifications": {
}, - "merchants": {
}, - "settlements": {
}, - "authorizations": {
}, - "transfers": {
}, - "payment_instruments": {
}, - "associated_identities": {
}, - "disputes": {
}, - "application": {
}
}
}
]
}, - "page": {
- "offset": 0,
- "limit": 20,
- "count": 1
}
}
Retrieve the details of a previously created Identity
.
Single Identity object
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
curl https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K \ -H "Content-Type: application/vnd.api+json" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
{- "id": "IDezsbY5qYujV7ecdrn8psrh",
- "created_at": "2022-10-11T00:37:03.02Z",
- "updated_at": "2022-10-11T00:37:03.02Z",
- "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
}
}, - "application": "APgPDQrLD52TYvqazjHJJchM",
- "entity": {
- "amex_mid": null,
- "annual_card_volume": 12000000,
- "business_address": {
- "line1": "741 Douglass St",
- "line2": "Apartment 8",
- "city": "San Mateo",
- "region": "CA",
- "postal_code": "94114",
- "country": "USA"
}, - "business_name": "Finix Flowers",
- "business_phone": "+1 (408) 756-4497",
- "business_tax_id_provided": true,
- "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
- "default_statement_descriptor": "Finix Flowers",
- "discover_mid": null,
- "dob": {
- "day": 27,
- "month": 6,
- "year": 1978
}, - "doing_business_as": "Finix Flowers",
- "email": "user@example.org",
- "first_name": "John",
- "has_accepted_credit_cards_previously": true,
- "incorporation_date": {
- "day": 27,
- "month": 6,
- "year": 1978
}, - "last_name": "Smith",
- "max_transaction_amount": 12000000,
- "mcc": "0742",
- "ownership_type": "PRIVATE",
- "personal_address": {
- "line1": "741 Douglass St",
- "line2": "Apartment 7",
- "city": "San Mateo",
- "region": "CA",
- "postal_code": "94114",
- "country": "USA"
}, - "phone": "1234567890",
- "principal_percentage_ownership": 50,
- "short_business_name": null,
- "tax_authority": null,
- "tax_id_provided": true,
- "title": "CEO",
- "url": "www.Finix.com"
}, - "tags": {
- "Studio Rating": "4.7"
}, - "_links": {
- "verifications": {
}, - "merchants": {
}, - "settlements": {
}, - "authorizations": {
}, - "transfers": {
}, - "payment_instruments": {
}, - "associated_identities": {
}, - "disputes": {
}, - "application": {
}
}
}
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.
Single Identity object
Error
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
curl https://finix.sandbox-payments-api.com/identities/IDrH4G2VTfNjn1VFkvhcyMYj \ -H "Content-Type: application/vnd.api+json" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -X PUT \ -d ' { "entity": { "email": "user@example.org", "first_name": "John", "last_name": "Smith", "phone": "7145677613" } }'
{- "id": "IDezsbY5qYujV7ecdrn8psrh",
- "created_at": "2022-10-11T00:37:03.02Z",
- "updated_at": "2022-10-11T00:37:03.02Z",
- "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
}
}, - "application": "APgPDQrLD52TYvqazjHJJchM",
- "entity": {
- "amex_mid": null,
- "annual_card_volume": 12000000,
- "business_address": {
- "line1": "741 Douglass St",
- "line2": "Apartment 8",
- "city": "San Mateo",
- "region": "CA",
- "postal_code": "94114",
- "country": "USA"
}, - "business_name": "Finix Flowers",
- "business_phone": "+1 (408) 756-4497",
- "business_tax_id_provided": true,
- "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
- "default_statement_descriptor": "Finix Flowers",
- "discover_mid": null,
- "dob": {
- "day": 27,
- "month": 6,
- "year": 1978
}, - "doing_business_as": "Finix Flowers",
- "email": "user@example.org",
- "first_name": "John",
- "has_accepted_credit_cards_previously": true,
- "incorporation_date": {
- "day": 27,
- "month": 6,
- "year": 1978
}, - "last_name": "Smith",
- "max_transaction_amount": 12000000,
- "mcc": "0742",
- "ownership_type": "PRIVATE",
- "personal_address": {
- "line1": "741 Douglass St",
- "line2": "Apartment 7",
- "city": "San Mateo",
- "region": "CA",
- "postal_code": "94114",
- "country": "USA"
}, - "phone": "1234567890",
- "principal_percentage_ownership": 50,
- "short_business_name": null,
- "tax_authority": null,
- "tax_id_provided": true,
- "title": "CEO",
- "url": "www.Finix.com"
}, - "tags": {
- "Studio Rating": "4.7"
}, - "_links": {
- "verifications": {
}, - "merchants": {
}, - "settlements": {
}, - "authorizations": {
}, - "transfers": {
}, - "payment_instruments": {
}, - "associated_identities": {
}, - "disputes": {
}, - "application": {
}
}
}
Create an associated Identity
for every owner with 25% or more ownership over the merchant.
Single Identity object
Error
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
curl https://finix.sandbox-payments-api.com/identities/IDgXNAaoy5d4TLkp5ze6gScA/associated_identities \ -H "Content-Type: application/vnd.api+json" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e -d ' { "entity": { "first_name": "John", "last_name": "Smith", "title": "Founder", "dob": { "month": 1, "day": 1, "year": 2013 }, "principal_percentage_ownership": 25, "phone": "1234567890", "personal_address": { "city": "San Francisco", "region": "CA", "postal_code": "90650", "line1": "123 Main Street", "country": "USA" }, "email": "john.smith@company1.com", "tax_id": "123456789" } }'
{- "id": "IDezsbY5qYujV7ecdrn8psrh",
- "created_at": "2022-10-11T00:37:03.02Z",
- "updated_at": "2022-10-11T00:37:03.02Z",
- "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
}
}, - "application": "APgPDQrLD52TYvqazjHJJchM",
- "entity": {
- "amex_mid": null,
- "annual_card_volume": 12000000,
- "business_address": {
- "line1": "741 Douglass St",
- "line2": "Apartment 8",
- "city": "San Mateo",
- "region": "CA",
- "postal_code": "94114",
- "country": "USA"
}, - "business_name": "Finix Flowers",
- "business_phone": "+1 (408) 756-4497",
- "business_tax_id_provided": true,
- "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
- "default_statement_descriptor": "Finix Flowers",
- "discover_mid": null,
- "dob": {
- "day": 27,
- "month": 6,
- "year": 1978
}, - "doing_business_as": "Finix Flowers",
- "email": "user@example.org",
- "first_name": "John",
- "has_accepted_credit_cards_previously": true,
- "incorporation_date": {
- "day": 27,
- "month": 6,
- "year": 1978
}, - "last_name": "Smith",
- "max_transaction_amount": 12000000,
- "mcc": "0742",
- "ownership_type": "PRIVATE",
- "personal_address": {
- "line1": "741 Douglass St",
- "line2": "Apartment 7",
- "city": "San Mateo",
- "region": "CA",
- "postal_code": "94114",
- "country": "USA"
}, - "phone": "1234567890",
- "principal_percentage_ownership": 50,
- "short_business_name": null,
- "tax_authority": null,
- "tax_id_provided": true,
- "title": "CEO",
- "url": "www.Finix.com"
}, - "tags": {
- "Studio Rating": "4.7"
}, - "_links": {
- "verifications": {
}, - "merchants": {
}, - "settlements": {
}, - "authorizations": {
}, - "transfers": {
}, - "payment_instruments": {
}, - "associated_identities": {
}, - "disputes": {
}, - "application": {
}
}
}
Retrieve a list of Associated Identities
for an Identity
.
limit | integer <int64> The number of entries to return. |
after_cursor | string Return every resource created after the cursor value. |
before_cursor | string Return every resource created before the cursor value. |
tags.key | string Filter by the |
tags.value | string Filter by the value of a |
List of Identity objects
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
curl https://finix.sandbox-payments-api.com/identities/IDf33pdVaTZGXVFNccdKvaPu/associated_identities \ -H "Content-Type: application/vnd.api+json" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
{- "_embedded": {
- "identities": [
- {
- "id": "IDrNRsZ2miEQcmGHCpo4rBQr",
- "created_at": "2022-08-16T18:44:27.46Z",
- "updated_at": "2022-08-16T18:44:27.46Z",
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "entity": {
- "amex_mid": null,
- "annual_card_volume": 12000000,
- "business_address": {
- "line1": "741 Douglass St",
- "line2": "Apartment 8",
- "city": "San Mateo",
- "region": "CA",
- "postal_code": "94114",
- "country": "USA"
}, - "business_name": "Petes Coffee",
- "business_phone": "+1 (408) 756-4497",
- "business_tax_id_provided": true,
- "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
- "default_statement_descriptor": "Petes Coffee",
- "discover_mid": null,
- "dob": {
- "day": 27,
- "month": 6,
- "year": 1978
}, - "doing_business_as": "Petes Coffee",
- "email": "user@example.org",
- "first_name": "dwayne",
- "has_accepted_credit_cards_previously": true,
- "incorporation_date": {
- "day": 27,
- "month": 6,
- "year": 1978
}, - "last_name": "xbc",
- "max_transaction_amount": 12000000,
- "mcc": "0742",
- "ownership_type": "PRIVATE",
- "personal_address": {
- "line1": "741 Douglass St",
- "line2": "Apartment 7",
- "city": "San Mateo",
- "region": "CA",
- "postal_code": "94114",
- "country": "USA"
}, - "phone": "1234567890",
- "principal_percentage_ownership": 50,
- "short_business_name": null,
- "tax_authority": null,
- "tax_id_provided": true,
- "title": "CEO",
- "url": "www.PetesCoffee.com"
}, - "tags": {
- "test_key_103": "test_val_103"
}, - "_links": {
- "verifications": {
}, - "merchants": {
}, - "settlements": {
}, - "authorizations": {
}, - "transfers": {
}, - "payment_instruments": {
}, - "associated_identities": {
}, - "disputes": {
}, - "application": {
}
}
}
]
}, - "page": {
- "offset": 0,
- "limit": 20,
- "count": 1
}
}