Docs
Guides
Explanatory and how-to content
API Reference
Technical documentation
Changelog
Release notes
Dashboard
Manage your account
Status
Service status
API Reference
Entities

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

The Entity object
{
  "corporation": {
    "address": {
      "city": "New York",
      "line1": "33 Liberty Street",
      "line2": null,
      "state": "NY",
      "zip": "10045"
    },
    "beneficial_owners": [
      {
        "beneficial_owner_id": "entity_setup_beneficial_owner_submission_vgkyk7dj5eb4sfhdbkx7",
        "company_title": "CEO",
        "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"
        },
        "prong": "control"
      }
    ],
    "incorporation_state": "NY",
    "industry_code": null,
    "name": "National Phonograph Company",
    "tax_identifier": "602214076",
    "website": "https://example.com"
  },
  "created_at": "2020-01-31T23:59:59Z",
  "description": null,
  "details_confirmed_at": null,
  "government_authority": null,
  "id": "entity_n8y8tnk2p9339ti393yi",
  "idempotency_key": null,
  "joint": null,
  "natural_person": 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"
    }
  ],
  "third_party_verification": null,
  "trust": null,
  "type": "entity"
}
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.

description
string
Nullable

The entity's description for display purposes.

details_confirmed_at
string
Nullable

The ISO 8601 time at which the Entity's details were most recently confirmed.

government_authority
dictionary
Nullable

Details of the government authority entity. Will be present if structure is equal to government_authority.

id
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.

joint
dictionary
Nullable

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

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.

supplemental_documents
array

Additional documentation associated with the entity. This is limited to the first 10 documents for an entity. If an entity has more than 10 documents, use the GET /entity_supplemental_documents list endpoint to retrieve them.

third_party_verification
dictionary
Nullable

A reference to data stored in a third-party verification service. Your integration may or may not use this field.

trust
dictionary
Nullable

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

type
string

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

List Entities
curl \
  --url "${INCREASE_URL}/entities" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
Parameters
cursor
string

Return the page of entries after this one.

limit
integer

Limit the size of the list that is returned. The default (and maximum) is 100 objects.

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.

created_at.after
string

Return results after this ISO 8601 timestamp.

created_at.before
string

Return results before this ISO 8601 timestamp.

created_at.on_or_after
string

Return results on or after this ISO 8601 timestamp.

created_at.on_or_before
string

Return results on or before this ISO 8601 timestamp.

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.

200 character maximum
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",
      "name": "National Phonograph Company",
      "tax_identifier": "602214076",
      "website": "https://example.com"
    },
    "structure": "corporation",
    "supplemental_documents": [
      {
        "file_id": "file_makxrc67oh9l6sg7w9yc"
      }
    ]
  }'
Parameters
corporation
dictionary

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

description
string

The description you choose to give the entity.

200 character maximum
government_authority
dictionary

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

joint
dictionary

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

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.

supplemental_documents
array

Additional documentation associated with the entity.

third_party_verification
dictionary

A reference to data stored in a third-party verification service. Your integration may or may not use this field.

trust
dictionary

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

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.

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.

Archive a beneficial owner for a corporate Entity
curl -X "POST" \
  --url "${INCREASE_URL}/entities/entity_n8y8tnk2p9339ti393yi/archive_beneficial_owner" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "beneficial_owner_id": "entity_setup_beneficial_owner_submission_vgkyk7dj5eb4sfhdbkx7"
  }'
Parameters
entity_id
string
Required

The identifier of the Entity associated with the Beneficial Owner that is being archived.

beneficial_owner_id
string
Required

The identifying details of anyone controlling or owning 25% or more of the corporation.

Confirm an Entity's details are correct

Depending on your program, you may be required to re-confirm an Entity's details on a recurring basis. After making any required updates, call this endpoint to record that your user confirmed their details.

curl -X "POST" \
  --url "${INCREASE_URL}/entities/entity_n8y8tnk2p9339ti393yi/confirm" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{}'
Parameters
entity_id
string
Required

The identifier of the Entity to confirm the details of.

confirmed_at
string

When your user confirmed the Entity's details. If not provided, the current time will be used.

Create a beneficial owner for a corporate Entity
curl -X "POST" \
  --url "${INCREASE_URL}/entities/entity_n8y8tnk2p9339ti393yi/create_beneficial_owner" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "beneficial_owner": {
      "company_title": "CEO",
      "individual": {
        "address": {
          "city": "New York",
          "country": "US",
          "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"
      ]
    }
  }'
Parameters
entity_id
string
Required

The identifier of the Entity to associate with the new Beneficial Owner.

beneficial_owner
dictionary
Required

The identifying details of anyone controlling or owning 25% or more of the corporation.

Update a Natural Person or Corporation's address
curl -X "POST" \
  --url "${INCREASE_URL}/entities/entity_n8y8tnk2p9339ti393yi/update_address" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "address": {
      "city": "New York",
      "line1": "33 Liberty Street",
      "line2": "Unit 2",
      "state": "NY",
      "zip": "10045"
    }
  }'
Parameters
entity_id
string
Required

The identifier of the Entity whose address is being updated.

address
dictionary
Required

The entity's physical address. Mail receiving locations like PO Boxes and PMB's are disallowed.

Update the address for a beneficial owner belonging to a corporate Entity
curl -X "POST" \
  --url "${INCREASE_URL}/entities/entity_n8y8tnk2p9339ti393yi/update_beneficial_owner_address" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "address": {
      "city": "New York",
      "country": "US",
      "line1": "33 Liberty Street",
      "line2": "Unit 2",
      "state": "NY",
      "zip": "10045"
    },
    "beneficial_owner_id": "entity_setup_beneficial_owner_submission_vgkyk7dj5eb4sfhdbkx7"
  }'
Parameters
entity_id
string
Required

The identifier of the Entity associated with the Beneficial Owner whose address is being updated.

address
dictionary
Required

The individual's physical address. Mail receiving locations like PO Boxes and PMB's are disallowed.

beneficial_owner_id
string
Required

The identifying details of anyone controlling or owning 25% or more of the corporation.

Update the industry code for a corporate Entity
curl -X "POST" \
  --url "${INCREASE_URL}/entities/entity_n8y8tnk2p9339ti393yi/update_industry_code" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "industry_code": "5132"
  }'
Parameters
entity_id
string
Required

The identifier of the Entity to update. This endpoint only accepts corporation entities.

industry_code
string
Required

The North American Industry Classification System (NAICS) code for the corporation's primary line of business. This is a number, like 5132 for Software Publishers. A full list of classification codes is available here.

200 character maximum