The Person object

This is an object representing a person associated with a Zoneless account. Persons are used to collect information about individuals associated with the account's legal entity, such as owners, directors, executives, and representatives.

Stripe API equivalent

Create a person

POST /v1/accounts/:id/persons

Update a person

POST /v1/accounts/:id/persons/:id

Retrieve a person

GET /v1/accounts/:id/persons/:id

List all persons

GET /v1/accounts/:id/persons

Delete a person

DELETE /v1/accounts/:id/persons/:id

Attributes

id string

Unique identifier for the object. Zoneless person IDs are prefixed with person_z_.

object string

String representing the object's type. Objects of the same type share the same value.

account string

The account the person is associated with.

addressnullable object

The person's address.

created timestamp

Time at which the object was created. Measured in seconds since the Unix epoch.

dobnullable object

The person's date of birth.

emailnullable string

The person's email address.

first_namenullable string

The person's first name.

future_requirementsnullable object

Information about the upcoming new requirements for this person, including what information needs to be collected, and by when.

id_number_provided boolean

Whether the person's id_number was provided. True if the full ID number was provided (e.g., a social security number in the U.S.).

last_namenullable string

The person's last name.

metadata object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

phonenullable string

The person's phone number.

relationship object

Describes the person's relationship to the account.

requirementsnullable object

Information about the requirements for this person, including what information needs to be collected, and by when.

ssn_last_4_provided boolean

Whether the last four digits of the person's Social Security number have been provided (U.S. only).

verification object

The person's verification status.

More attributes

THE PERSON OBJECT

{
  "id": "person_z_1Nv0FGQ9RKHgCVdK",
  "object": "person",
  "account": "acct_z_1Nv0FGQ9RKHgCVdK",
  "address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "123 Market St",
    "line2": "Suite 400",
    "postal_code": "94105",
    "state": "CA"
  },
  "created": 1704067200,
  "dob": {
    "day": 15,
    "month": 6,
    "year": 1990
  },
  "email": "tom.jones@example.com",
  "first_name": "Tom",
  "future_requirements": {
    "alternatives": [],
    "currently_due": [],
    "errors": [],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": []
  },
  "id_number_provided": false,
  "last_name": "Jones",
  "metadata": {},
  "phone": "+14155551234",
  "platform_account": "acct_z_Platform123abc",
  "relationship": {
    "authorizer": null,
    "director": false,
    "executive": false,
    "legal_guardian": null,
    "owner": true,
    "percent_ownership": 100,
    "representative": true,
    "title": "CEO"
  },
  "requirements": {
    "alternatives": [],
    "currently_due": [],
    "errors": [],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": []
  },
  "ssn_last_4_provided": true,
  "verification": {
    "additional_document": null,
    "details": null,
    "details_code": null,
    "document": {
      "back": null,
      "details": null,
      "details_code": null,
      "front": null
    },
    "status": "unverified"
  }
}

Create a person

Creates a new person associated with an account. You can create persons to represent owners, directors, executives, or representatives of a business.

ENDPOINTS

POST /v1/accounts/:id/persons

Parameters

address object

The person's address.

dob object

The person's date of birth.

email string

The person's email address. Maximum 800 characters.

first_name string

The person's first name. Maximum 100 characters.

id_number string

The person's ID number, as appropriate for their country. For example, a social security number in the U.S., social insurance number in Canada, etc. The value is not stored; only a flag indicating it was provided is set.

last_name string

The person's last name. Maximum 100 characters.

metadata object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

phone string

The person's phone number.

relationship object

The relationship that this person has with the account's legal entity.

ssn_last_4 string

The last four digits of the person's Social Security number (U.S. only). Must be exactly 4 digits. The value is not stored; only a flag indicating it was provided is set.

verification object

The person's verification documents.

Returns

Returns a Person object if the call succeeds.

POST/v1/accounts/:id/persons

import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const person = await zoneless.accounts.createPerson(
  'acct_z_1032D82eZvKYlo2C',
  {
    first_name: 'John',
    last_name: 'Doe',
  }
);

RESPONSE

{
  "id": "person_z_1Nv0FGQ9RKHgCVdK",
  "object": "person",
  "account": "acct_z_1032D82eZvKYlo2C",
  "address": null,
  "created": 1684518375,
  "dob": {
    "day": null,
    "month": null,
    "year": null
  },
  "email": null,
  "first_name": "John",
  "future_requirements": {
    "alternatives": [],
    "currently_due": [],
    "errors": [],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": []
  },
  "id_number_provided": false,
  "last_name": "Doe",
  "metadata": {},
  "phone": null,
  "platform_account": "acct_z_Platform123abc",
  "relationship": {
    "authorizer": null,
    "director": false,
    "executive": false,
    "legal_guardian": null,
    "owner": false,
    "percent_ownership": null,
    "representative": false,
    "title": null
  },
  "requirements": {
    "alternatives": [],
    "currently_due": [],
    "errors": [],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": []
  },
  "ssn_last_4_provided": false,
  "verification": {
    "additional_document": null,
    "details": null,
    "details_code": null,
    "document": {
      "back": null,
      "details": null,
      "details_code": null,
      "front": null
    },
    "status": "unverified"
  }
}

Update a person

Updates an existing person. Any parameters not provided are left unchanged.

ENDPOINTS

POST /v1/accounts/:id/persons/:id

Parameters

address object

The person's address.

dob object

The person's date of birth.

email string

The person's email address. Maximum 800 characters.

first_name string

The person's first name. Maximum 100 characters.

id_number string

last_name string

The person's last name. Maximum 100 characters.

metadata object

Set of key-value pairs that you can attach to an object. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

phone string

The person's phone number.

relationship object

The relationship that this person has with the account's legal entity.

ssn_last_4 string

The last four digits of the person's Social Security number (U.S. only). Must be exactly 4 digits. The value is not stored; only a flag indicating it was provided is set.

verification object

The person's verification documents.

Returns

Returns a Person object if the call succeeds.

POST/v1/accounts/:id/persons/:id

import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const person = await zoneless.accounts.updatePerson(
  'acct_z_1032D82eZvKYlo2C',
  'person_z_1MqjB62eZvKYlo2CaeEJzKVR',
  {
    metadata: {
      order_id: '6735',
    },
  }
);

RESPONSE

{
  "id": "person_z_1MqjB62eZvKYlo2CaeEJzKVR",
  "object": "person",
  "account": "acct_z_1032D82eZvKYlo2C",
  "address": null,
  "created": 1680035496,
  "dob": {
    "day": null,
    "month": null,
    "year": null
  },
  "email": null,
  "first_name": "Jane",
  "future_requirements": {
    "alternatives": [],
    "currently_due": [],
    "errors": [],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": []
  },
  "id_number_provided": false,
  "last_name": "Diaz",
  "metadata": {
    "order_id": "6735"
  },
  "phone": null,
  "platform_account": "acct_z_Platform123abc",
  "relationship": {
    "authorizer": null,
    "director": false,
    "executive": false,
    "legal_guardian": null,
    "owner": false,
    "percent_ownership": null,
    "representative": false,
    "title": null
  },
  "requirements": {
    "alternatives": [],
    "currently_due": [],
    "errors": [],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": []
  },
  "ssn_last_4_provided": false,
  "verification": {
    "additional_document": null,
    "details": null,
    "details_code": null,
    "document": {
      "back": null,
      "details": null,
      "details_code": null,
      "front": null
    },
    "status": "unverified"
  }
}

Retrieve a person

Retrieves an existing person.

ENDPOINTS

GET /v1/accounts/:id/persons/:id

Parameters

No parameters.

Returns

Returns a Person object if the call succeeds. If the person ID does not exist or does not belong to the account, this call raises an error.

GET/v1/accounts/:id/persons/:id

import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const person = await zoneless.accounts.retrievePerson(
  'acct_z_1032D82eZvKYlo2C',
  'person_z_1MqjB62eZvKYlo2CaeEJzKVR'
);

RESPONSE

{
  "id": "person_z_1N9XNb2eZvKYlo2CjPX7xF6F",
  "object": "person",
  "account": "acct_z_1032D82eZvKYlo2C",
  "address": null,
  "created": 1684518375,
  "dob": {
    "day": null,
    "month": null,
    "year": null
  },
  "email": null,
  "first_name": null,
  "future_requirements": {
    "alternatives": [],
    "currently_due": [],
    "errors": [],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": []
  },
  "id_number_provided": false,
  "last_name": null,
  "metadata": {},
  "phone": null,
  "platform_account": "acct_z_Platform123abc",
  "relationship": {
    "authorizer": null,
    "director": false,
    "executive": false,
    "legal_guardian": null,
    "owner": false,
    "percent_ownership": null,
    "representative": false,
    "title": null
  },
  "requirements": {
    "alternatives": [],
    "currently_due": [],
    "errors": [],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": []
  },
  "ssn_last_4_provided": false,
  "verification": {
    "additional_document": null,
    "details": null,
    "details_code": null,
    "document": {
      "back": null,
      "details": null,
      "details_code": null,
      "front": null
    },
    "status": "unverified"
  }
}

List all persons

Returns a list of people associated with the account's legal entity. The people are returned sorted by creation date, with the most recent people appearing first.

ENDPOINTS

GET /v1/accounts/:id/persons

Parameters

No required parameters.

More attributes

Returns

A dictionary with a data property that contains an array of up to limit people, starting after person starting_after. Each entry in the array is a separate Person object. If no more people are available, the resulting array will be empty.

GET/v1/accounts/:id/persons

import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const persons = await zoneless.accounts.listPersons(
  'acct_z_1032D82eZvKYlo2C',
  {
    limit: 3,
  }
);

RESPONSE

{
  "object": "list",
  "url": "/v1/accounts/acct_z_1032D82eZvKYlo2C/persons",
  "has_more": false,
  "data": [
    {
      "id": "person_z_1MqjB62eZvKYlo2CaeEJzKVR",
      "object": "person",
      "account": "acct_z_1032D82eZvKYlo2C",
      "address": null,
      "created": 1680035496,
      "dob": {
        "day": null,
        "month": null,
        "year": null
      },
      "email": null,
      "first_name": "Jane",
      "future_requirements": {
        "alternatives": [],
        "currently_due": [],
        "errors": [],
        "eventually_due": [],
        "past_due": [],
        "pending_verification": []
      },
      "id_number_provided": false,
      "last_name": "Diaz",
      "metadata": {},
      "phone": null,
      "platform_account": "acct_z_Platform123abc",
      "relationship": {
        "authorizer": null,
        "director": false,
        "executive": false,
        "legal_guardian": null,
        "owner": false,
        "percent_ownership": null,
        "representative": false,
        "title": null
      },
      "requirements": {
        "alternatives": [],
        "currently_due": [],
        "errors": [],
        "eventually_due": [],
        "past_due": [],
        "pending_verification": []
      },
      "ssn_last_4_provided": false,
      "verification": {
        "additional_document": null,
        "details": null,
        "details_code": null,
        "document": {
          "back": null,
          "details": null,
          "details_code": null,
          "front": null
        },
        "status": "unverified"
      }
    }
  ]
}

Delete a person

Deletes an existing person's relationship to the account's legal entity.

ENDPOINTS

DELETE /v1/accounts/:id/persons/:id

Parameters

No parameters.

Returns

Returns the deleted Person object with a deleted property set to true.

DELETE/v1/accounts/:id/persons/:id

import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const deleted = await zoneless.accounts.deletePerson(
  'acct_z_1032D82eZvKYlo2C',
  'person_z_1MqjB62eZvKYlo2CaeEJzKVR'
);

RESPONSE

{
  "id": "person_z_1MqjB62eZvKYlo2CaeEJzKVR",
  "object": "person",
  "deleted": true
}