Create an Identity

Create an Identity for your merchant 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

Request
Request Body schema: application/hal+json
Any of:
object or null

Addition underwriting details required to verify Identities.

object

The underwriting details required to verify Identities.

object

Key value pair for annotating custom meta data (e.g. order numbers).

Responses
201

Single Identity object

Response Schema: application/hal+json
Any of:
object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

object or null

Additional underwriting data that's required to verify the Identity.

application
string non-empty

ID of the Application associated with the Identity.

created_at
string <date-time>

Timestamp of when the object was created.

object

The underwriting details required to verify the Identity.

id
string non-empty

The ID of the Identity resource.

object

Key value pair for annotating custom meta data (e.g. order numbers).

updated_at
string <date-time>

Timestamp of when the object was last updated.

400

Error

401

Authentication information is missing or invalid

403

Forbidden

406

Not Acceptable

post/identities
Request samples 
Response samples 
application/hal+json
{}
List Identities
Retrieves a list of Identities.


Request 
query Parameters
after_cursor
string
Return every resource created after the cursor value.


 
before_cursor
string
Return every resource created before the cursor value.


 
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.


 
created_at.gte
string
Filter where created_at is after the given date.


 
 Example:  created_at.gte=created_at.gte=2019-06-15
created_at.lte
string
Filter where created_at is before the given date.


 
 Example:  created_at.lte=created_at.lte=2019-06-15
default_statement_descriptor
string
Filter by the default_statement_descriptor.


 
email
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 Identity.


 
 Example:  first_name=first_name=Daphne
id
string
Filter by id.


 
last_name
string
Filter by the last name of the person associated to the Identity.


 
 Example:  last_name=kline
limit
integer
The numbers of items to return.


 
 Example:  limit=10
sort
string
Specify key to be used for sorting the collection.


 
title
string
Filter by the title if available.


 
 Example:  title=ceo
Responses 
200
List of Identity objects


Response Schema: application/hal+json
object
List of Identity resources.


 
object
For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.


 
object
Details the page that's returned.


 
401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


get/identities
Request samples 
curl https://finix.sandbox-payments-api.com/identities \
  -H "Content-Type: application/vnd.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/hal+json
{}
Fetch an Identity
Retrieve the details of a previously created Identity.


Request 
path Parameters
identity_id
required
string
ID of the Identity to fetch.


 
Responses 
200
Single Identity object


Response Schema: application/hal+json
Any of:
object
For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.


 
object or null
Additional underwriting data that's required to verify the Identity.


 
application
string  non-empty 
ID of the Application associated with the Identity.


 
created_at
string <date-time> 
Timestamp of when the object was created.


 
object
The underwriting details required to verify the Identity.


 
id
string  non-empty 
The ID of the Identity resource.


 
object
Key value pair for annotating custom meta data (e.g. order numbers).


 
updated_at
string <date-time> 
Timestamp of when the object was last updated.


 
401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


get/identities/{identity_id}
Request samples 
curl https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K \
  -H "Content-Type: application/vnd.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/hal+json
{}
Update an Identity
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.


Request 
path Parameters
identity_id
required
string
ID of the Identity to fetch.


 
Request Body schema: application/hal+json
Any of:
object
Additional underwriting data that's required to verify the Identity of merchants.


 
object
Underwriting data that's required to verify the Identity.


 
object
Key value pair for annotating custom meta data (e.g. order numbers).


 
Responses 
200
Single Identity object


Response Schema: application/hal+json
Any of:
object
For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.


 
object or null
Additional underwriting data that's required to verify the Identity.


 
application
string  non-empty 
ID of the Application associated with the Identity.


 
created_at
string <date-time> 
Timestamp of when the object was created.


 
object
The underwriting details required to verify the Identity.


 
id
string  non-empty 
The ID of the Identity resource.


 
object
Key value pair for annotating custom meta data (e.g. order numbers).


 
updated_at
string <date-time> 
Timestamp of when the object was last updated.


 
400
Error


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


put/identities/{identity_id}
Request samples 
Response samples 
application/hal+json
{}
Create an Associated Identity
Create an associated Identity for every owner with 25% or more ownership over the merchant.


Request 
path Parameters
identity_id
required
string
ID of Identity to associate object with.


 
Request Body schema: application/hal+json
object
Underwriting data that's required to verify the Identity.


 
object
Key value pair for annotating custom meta data (e.g. order numbers).


 
Responses 
201
Single Identity object


Response Schema: application/hal+json
Any of:
object
For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.


 
object or null
Additional underwriting data that's required to verify the Identity.


 
application
string  non-empty 
ID of the Application associated with the Identity.


 
created_at
string <date-time> 
Timestamp of when the object was created.


 
object
The underwriting details required to verify the Identity.


 
id
string  non-empty 
The ID of the Identity resource.


 
object
Key value pair for annotating custom meta data (e.g. order numbers).


 
updated_at
string <date-time> 
Timestamp of when the object was last updated.


 
400
Error


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


post/identities/{identity_id}/associated_identities
Request samples 
curl https://finix.sandbox-payments-api.com/identities/IDgXNAaoy5d4TLkp5ze6gScA/associated_identities \
  -H "Content-Type: application/vnd.json+api" \
  -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"
    }
}'

Response samples 
application/hal+json
{}
List Associated Identities
Retrieve a list of Associated Identities for an Identity.


Request 
path Parameters
identity_id
required
string
ID of Identity to associate object with.


 
query Parameters
after_cursor
string
Return every resource created after the cursor value.


 
before_cursor
string
Return every resource created before the cursor value.


 
limit
integer <int64> 
The number of entries to return.


 
Responses 
200
List of Identity objects


Response Schema: application/hal+json
object
List of Identity resources.


 
object
For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.


 
object
Details the page that's returned.


 
401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


get/identities/{identity_id}/associated_identities
Request samples 
curl https://finix.sandbox-payments-api.com/identities/IDf33pdVaTZGXVFNccdKvaPu/associated_identities \
  -H "Content-Type: application/vnd.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/hal+json
{}
Verify an Identity
Verify an Identity.


Request 
path Parameters
identity_id
required
string
ID of Identity to verify.


 
Request Body schema: application/hal+json
identity
string
ID of the Identity resource associated with the Merchant.


 
merchant
string
The ID of the Merchant.


 
processor
string or null
Set the acquiring processor. Avalible values include: 
  • DUMMY_V1
  • LITLE_V1
  • MASTERCARD_V1
  • VISA_V1
  • NMI_V1
  • VANTIV_V1
Use DUMMY_V1 or  null to use your sandbox. For more details on which processor to use, reach out to your Finix point of contact or email Finix Support.


 
object
Key value pair for annotating custom meta data (e.g. order numbers).


 
Responses 
201
Single Verification object


Response Schema: application/hal+json
object
For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.


 
application
string
ID of the Application the Merchant was created under.


 
created_at
string <date-time> 
Timestamp of when the object was created.


 
id
string
The ID of the Verification attempt (begins with VIXXX).


 
identity
string or null
ID of the Identity that created the Merchant.


 
merchant
string or null
ID of the Merchant resource.


 
merchant_identity
string or null
ID of the Identity associated with the Merchant.


 
messages
Array of objects
Provides additional details about the verification (e.g why it failed). This field is usually null.


 
payment_instrument
string or null
The Payment Instrument that'll be used to settle the Merchant's processed funds.


 
processor
string
Name of the verification processor.


 
(Raw (object or null)) or (Raw (string or null))
Raw response from the processor.


 
state
string
The status of the Verification request.


 Enum: "PENDING" "SUCCEEDED" "FAILED"  
object
Key value pair for annotating custom meta data (e.g. order numbers).


 
trace_id
string
Trace ID of the Verification. The processor sends back the trace_id so you can track the verification end-to-end.


 
updated_at
string <date-time> 
Timestamp of when the object was last updated.


 
400
Error


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


post/identities/{identity_id}/verifications
Request samples 
Response samples 
application/hal+json
{}