Entities

Entities are the legal entities that own accounts. They can be people, corporations, partnerships, government authorities, or trusts. To learn more, see Entities.

Events

Your application can listen to webhooks about this resource. The events about Entities will have the categories "entity.created" or "entity.updated" .

The Entity object

{
  "corporation": {
    "address": {
      "city": "New York",
      "country": "US",
      "line1": "33 Liberty Street",
      "line2": null,
      "state": "NY",
      "zip": "10045"
    },
    "beneficial_owners": [
      {
        "company_title": "CEO",
        "id": "entity_beneficial_owner_vozma8szzu1sxezp5zq6",
        "individual": {
          "address": {
            "city": "New York",
            "country": "US",
            "line1": "33 Liberty Street",
            "line2": null,
            "state": "NY",
            "zip": "10045"
          },
          "date_of_birth": "1970-01-31",
          "identification": {
            "method": "social_security_number",
            "number_last4": "1120"
          },
          "name": "Ian Crease"
        },
        "prongs": [
          "control",
          "ownership"
        ]
      }
    ],
    "beneficial_ownership_exemption_reason": null,
    "email": null,
    "incorporation_state": "NY",
    "industry_code": null,
    "legal_identifier": {
      "category": "us_employer_identification_number",
      "value": "602214076"
    },
    "name": "National Phonograph Company",
    "website": "https://example.com"
  },
  "created_at": "2020-01-31T23:59:59Z",
  "creating_entity_onboarding_session_id": null,
  "description": null,
  "details_confirmed_at": null,
  "government_authority": null,
  "id": "entity_n8y8tnk2p9339ti393yi",
  "idempotency_key": null,
  "joint": null,
  "natural_person": null,
  "risk_rating": null,
  "status": "active",
  "structure": "corporation",
  "supplemental_documents": [
    {
      "created_at": "2020-01-31T23:59:59Z",
      "entity_id": "entity_n8y8tnk2p9339ti393yi",
      "file_id": "file_makxrc67oh9l6sg7w9yc",
      "idempotency_key": null,
      "type": "entity_supplemental_document"
    }
  ],
  "terms_agreements": [],
  "third_party_verification": null,
  "trust": null,
  "type": "entity",
  "validation": null
}

Attributes

corporation

dictionary

Nullable

Details of the corporation entity. Will be present if structure is equal to corporation.

created_at

string

The ISO 8601 time at which the Entity was created.

creating_entity_onboarding_session_id

string

Nullable

The identifier of the Entity Onboarding Session that was used to create this Entity, if any.

More about Entity Onboarding Sessions.

string

The entity’s identifier.

idempotency_key

string

Nullable

The idempotency key you chose for this object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about idempotency.

natural_person

dictionary

Nullable

Details of the natural person entity. Will be present if structure is equal to natural_person.

status

enum

The status of the entity.

structure

enum

The entity’s legal structure.

type

string

A constant representing the object’s type. For this resource it will always be entity.

validation

dictionary

Nullable

The validation results for the entity. Learn more about validations.

More!

description

string

Nullable

details_confirmed_at

string

Nullable

government_authority

dictionary

Nullable

joint

dictionary

Nullable

risk_rating

dictionary

Nullable

supplemental_documents

array

terms_agreements

array

third_party_verification

dictionary

Nullable

trust

dictionary

Nullable

List Entities

curl \
  --url "${INCREASE_URL}/entities" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"

Returns a list response :

{
  "data": [
    { /* Entity object */ },
    { /* Entity object */ }
    /* ... */
  ],
  "next_cursor": "v57w5d",
}

Parameters

status.in

array of strings

Filter Entities for those with the specified status or statuses. For GET requests, this should be encoded as a comma-delimited string, such as ?in=one,two,three.

idempotency_key

string

Filter records to the one with the specified idempotency_key you chose for that object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about idempotency.

Between 1 and 200 characters

cursor

string

limit

integer

created_at.after

string

created_at.before

string

created_at.on_or_after

string

created_at.on_or_before

string

Create an Entity

curl -X "POST" \
  --url "${INCREASE_URL}/entities" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "corporation": {
      "address": {
        "city": "New York",
        "line1": "33 Liberty Street",
        "state": "NY",
        "zip": "10045"
      },
      "beneficial_owners": [
        {
          "company_title": "CEO",
          "individual": {
            "address": {
              "city": "New York",
              "line1": "33 Liberty Street",
              "state": "NY",
              "zip": "10045"
            },
            "date_of_birth": "1970-01-31",
            "identification": {
              "method": "social_security_number",
              "number": "078051120"
            },
            "name": "Ian Crease"
          },
          "prongs": [
            "control"
          ]
        }
      ],
      "incorporation_state": "NY",
      "legal_identifier": {
        "category": "us_employer_identification_number",
        "value": "602214076"
      },
      "name": "National Phonograph Company",
      "website": "https://example.com"
    },
    "structure": "corporation"
  }'

Parameters

corporation

dictionary

Details of the corporation entity to create. Required if structure is equal to corporation.

natural_person

dictionary

Details of the natural person entity to create. Required if structure is equal to natural_person. Natural people entities should be submitted with social_security_number or individual_taxpayer_identification_number identification methods.

structure

enum

Required

The type of Entity to create.

description

string

government_authority

dictionary

joint

dictionary

risk_rating

dictionary

supplemental_documents

array

terms_agreements

array

third_party_verification

dictionary

trust

dictionary

Retrieve an Entity

curl \
  --url "${INCREASE_URL}/entities/entity_n8y8tnk2p9339ti393yi" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"

Parameters

entity_id

string

Required

The identifier of the Entity to retrieve.

More about Entities.

Update an Entity

curl -X "PATCH" \
  --url "${INCREASE_URL}/entities/entity_n8y8tnk2p9339ti393yi" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "corporation": {
      "address": {
        "city": "New York",
        "country": "US",
        "line1": "33 Liberty Street",
        "line2": "Unit 2",
        "state": "NY",
        "zip": "10045"
      }
    },
    "risk_rating": {
      "rated_at": "2020-01-31T23:59:59Z",
      "rating": "low"
    }
  }'

Parameters

entity_id

string

Required

The entity identifier.

More about Entities.

corporation

dictionary

Details of the corporation entity to update. If you specify this parameter and the entity is not a corporation, the request will fail.

government_authority

dictionary

Details of the government authority entity to update. If you specify this parameter and the entity is not a government authority, the request will fail.

natural_person

dictionary

Details of the natural person entity to update. If you specify this parameter and the entity is not a natural person, the request will fail.

details_confirmed_at

string

risk_rating

dictionary

terms_agreements

array

third_party_verification

dictionary

trust

dictionary

Archive an Entity

curl -X "POST" \
  --url "${INCREASE_URL}/entities/entity_n8y8tnk2p9339ti393yi/archive" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"

Parameters

entity_id

string

Required

The identifier of the Entity to archive. Any accounts associated with an entity must be closed before the entity can be archived.

More about Entities.

Sandbox: Simulate validation of an Entity

Simulate updates to an Entity’s validation. In production, Know Your Customer validations run automatically for eligible programs. While developing, use this API to simulate issues with information submissions.

curl -X "POST" \
  --url "${INCREASE_URL}/simulations/entities/entity_n8y8tnk2p9339ti393yi/update_validation" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "issues": [
      {
        "category": "entity_tax_identifier"
      }
    ]
  }'

Parameters

entity_id

string

Required

The identifier of the Entity whose validation status to update.

More about Entities.

issues

array

Required

The validation issues to attach. If no issues are provided, the validation status will be set to valid.