Create a record | Parallel Developer Documentation

Version: Current – v2.x

This endpoint can be used to create a record.

HTTP Request

The specific path to call depends on whether you are creating an individual or business record. Refer to the following to determine which endpoint to call:

Request Parameters

Parameter Description
first_name (string) Required The first name of the individual.
last_name (string) Required The last name of the individual.
email (string) Optional. The email address for the individual.
middle_name (string) Optional. The middle name of the individual.
phone (string) Optional. The phone number for the individual in standard E.164 format with a country code prefix (i.e., "+12121234567").
birth_date (string) Optional. String YYYY-MM-DD date representing the individual's date of birth.
birth_place (string) Optional. The birth place of the individual.
marital_status (string) Optional. The individual's marital status. Can be one of:
- single
- married
- separated
- divorced
citizenship_country (string) Optional. ISO Alpha-2 Country Code representing the individual's country of citizenship.
gender (string) Optional. The gender of the individual. Can be one of:
- male
- female
- other
name_suffix (string) Optional. The name suffix of the individual (e.g., "Jr.", "Sr.", "III").
secondary_citizenship_countries (string) Optional. An array of ISO Alpha-2 Country Code country codes representing the individuals secondary countries of citizenship.
tax_country (string) Optional. ISO Alpha-2 Country Code representing the individual's tax country.
tax_id (string) Optional. The individual's tax ID number (e.g. SSN).
secondary_tax_ids (array) Optional. An array of objects, each containing the following keys:
- tax_country: The secondary tax country of the individual, represented by an ISO Alpha-2 Country Code.
- tax_id: The secondary tax id number of the individual.
us_person (boolean) Optional. Indicates whether the individual is a U.S. person for federal tax purposes (includes but not limited to an individual U.S. citizen or U.S. resident alien).
residence_location (object) Optional. A Location object representing the individual's residence address.
domicile_location (object) Optional. A Location object representing the individual's legal address, where they pay taxes.
external_id (string) Optional. A custom unique identifier for this record. See Using an External Identifier for more information.
traits (object[ \]) Optional. An array of objects representing record trait values of the individual. See Setting Record Trait Values for more information.

Sample payload

{
  "first_name": "John",
  "last_name": "Smith",
  "middle_name": "Roger",
  "name_suffix": "Jr.",
  "gender": "male",
  "email": "jsmith@email.com",
  "phone": "12125555555",
  "birth_date": "1970-01-01",
  "birth_place": "United States",
  "marital_status": "single",
  "citizenship_country": "US",
  "secondary_citizenship_countries": ["CA"],
  "tax_country": "US",
  "tax_id": "123-45-6789",
  "secondary_tax_ids": [
    {
      "tax_country": "CA",
      "tax_id": "000-999-000"
    }
  ],
  "us_person": true,
  "external_id": "unique_external_id_123",
  "residence_location": {
    "address_one": "123 Fake St",
    "address_two": "Apt 3",
    "city": "New York",
    "region": null,
    "postal_code": "10011",
    "state": "NY",
    "country": "US"
  },
  "domicile_location": {
    "address_one": "123 Fake St",
    "address_two": "Apt 3",
    "city": "New York",
    "region": null,
    "postal_code": "10011",
    "state": "NY",
    "country": "US"
  },
  "traits": [
    {
      "id": "commitment-amount",
      "value": "500000.25"
    },
    {
      "id": "external-ids",
      "value": ["us:12345-67890", "ca:12345-67890"]
    },
    {
      "id": "priority",
      "value": "Medium"
    },
    {
      "id": "refresh-date",
      "value": "2025-05-10"
    },
    {
      "id": "returning-investor",
      "value": true
    }
  ]
}
Parameter Description
name (string) Required The full, legal name of the business.
business_type (string) Optional. The type of business. See Business Profile for possible values.
incorporation_country (string) Optional. ISO Alpha-2 Country Code representing the business' country of incorporation.
incorporation_region (string) Optional. The business's region of incorporation, if applicable. Required if incorporation_country is provided and outside of the United States.
incorporation_state (string) Optional. String 2-letter state code; The business's state of incorporation. Required if incorporation_country is provided and is the United States.
tax_country (string) Optional. ISO Alpha-2 Country Code representing the business's tax country.
tax_id (string) Optional. The business's provided tax id number (e.g. EIN).
secondary_tax_ids (array) Optional. An array of objects, each containing the following keys:
- tax_country: The secondary tax country of the business, represented by an ISO Alpha-2 Country Code.
- tax_id: The secondary tax id number of the business.
us_person (boolean) Optional. Indicates whether the business is a U.S. person for federal tax purposes.
primary_contact (object) Optional. An object containing the following keys:
- id: The ID of the individual record associated with the primary contact.
control_persons (array) Optional. An array of objects containing the following keys:
- id: The ID of the individual record associated with the control person.
- title: The title of the control person. E.g. CEO.
beneficial_owners (array) Optional. An array of objects containing the following keys:
- id: The ID of the individual or business record associated with the beneficial owner.
- ownership_percent: The fractional amount of direct ownership this entity has of the business (float number > 0.0 and ≤ 1.0). E.g. 0.25.
principal_location (object) Optional. A Location object representing where the business primarily conducts its business.
domicile_location (object) Optional. A Location object representing the business's legal domicile.
external_id (string) Optional. A custom unique identifier for this record. See Using an External Identifier for more information.
traits (object[ \]) Optional. An array of objects representing trait values of the individual. 
{
  "name": "Hooli LTD",
  "business_type": "C Corporation",
  "incorporation_country": "US",
  "incorporation_state": "DE",
  "tax_country": "US",
  "tax_id": "12-3456789",
  "secondary_tax_ids": [
    {
      "tax_country": "CA",
      "tax_id": "000-999-000"
    }
  ],
  "us_person": true,
  "external_id": "unique_external_id_456",
  "primary_contact": {
    "id": "UG9kVXNlclJlY29yZDox"
  },
  "control_persons": [
    {
      "id": "UG9kVXNlclJlY29yZDox",
      "title": "CEO"
    }
  ],
  "beneficial_owners": [
    {
      "id": "UG9kVXNlclJlY29yZDox",
      "ownership_percent": 0.25
    }
  ],
  "principal_location": {
    "address_one": "22 Wall St",
    "address_two": null,
    "city": "New York",
    "region": null,
    "postal_code": "10005",
    "state": "NY",
    "country": "US"
  },
  "domicile_location": {
    "address_one": "22 Wall St",
    "address_two": null,
    "city": "New York",
    "region": null,
    "postal_code": "10005",
    "state": "NY",
    "country": "US"
  },
  "traits": [
    {
      "id": "commitment-amount",
      "value": "500000.25"
    },
    {
      "id": "external-ids",
      "value": ["us:12345-67890", "ca:12345-67890"]
    },
    {
      "id": "priority",
      "value": "Medium"
    },
    {
      "id": "refresh-date",
      "value": "2025-05-10"
    },
    {
      "id": "returning-investor",
      "value": true
    }
  ]
}

Response Parameters

Returns a Record after successful record creation.

Example Response

{
  "data": {
    "id": "UG9kVXNlclJlY29yZDoxNzM=",
    "type": "individual",
    "external_id": "unique_external_id_123",
    "created_at": "2023-09-01T09:57:23Z",
    "details": {
      "email": "jsmith@email.com",
      "phone": "+12125555555",
      "first_name": "John",
      "middle_name": "Roger",
      "last_name": "Smith",
      "birth_date": "1970-01-01",
      "birth_place": "United States",
      "residence_location": {
        "address_one": "123 Fake St",
        "address_two": "Apt 3",
        "city": "New York",
        "region": null,
        "postal_code": "10011",
        "state": "NY",
        "country": "US"
      },
      "domicile_location": {
        "address_one": "123 Fake St",
        "address_two": "Apt 3",
        "city": "New York",
        "region": null,
        "postal_code": "10011",
        "state": "NY",
        "country": "US"
      },
      "marital_status": "single",
      "citizenship_country": "US",
      "secondary_citizenship_countries": ["CA"],
      "tax_country": "US",
      "tax_id": "123-45-6789",
      "secondary_tax_ids": [
        {
          "tax_country": "CA",
          "tax_id": "000-999-000"
        }
      ],
      "us_person": true,
      "accreditation_assertion_type": null,
      "user_session": null,
      "accreditation_status": null,
      "indicated_unaccredited_at": null,
      "accreditation_expires_at": null,
      "consistency_summary": {
        "tin_multiple_match": null,
        "possibly_deceased": null,
        "address_records_match_level": null,
        "address_submitter_match": null,
        "name_records_match_level": null,
        "name_tax_match": null,
        "tin_records_match_level": null,
        "overall_records_match_level": null,
        "address_id_match": null,
        "birth_date_id_match": null,
        "birth_date_records_match_level": null,
        "id_validity": null,
        "id_matching_sides": true,
        "name_id_match": null,
        "address_id_value": null,
        "birth_date_id_value": null,
        "id_selfie_similarity_level": null,
        "name_id_value": null,
        "selfie_liveness_probability_level": null,
        "name_tax_value": null
      },
      "change_created_at": "2023-09-01T09:57:23Z",
      "change_created_by": null,
      "change_id": "UG9kVXNlckRhdGFFbnRyeTo4MDA=",
      "id_expiration": null,
      "source": "api"
    },
    "traits": [
      {
        "id": "commitment-amount",
        "name": "Commitment Amount",
        "type": "number",
        "value": "500000.25"
      },
      {
        "id": "external-ids",
        "name": "External IDs",
        "type": "strings",
        "value": ["us:12345-67890", "ca:12345-67890"]
      },
      {
        "id": "priority",
        "name": "Priority",
        "type": "string",
        "value": "Medium"
      },
      {
        "id": "refresh-date",
        "name": "Refresh Date",
        "type": "date",
        "value": "2025-05-10"
      },
      {
        "id": "returning-investor",
        "name": "Returning Investor",
        "type": "boolean",
        "value": true
      }
    ],
    "identity_link_established_at": null,
    "archived_at": null,
    "identity_link_expiration_requested_by": null,
    "identity_link_expires_at": null,
    "current_status": {
      "status": "open",
      "notes": null,
      "set_by": null,
      "set_at": "2023-09-01T09:57:23Z"
    },
    "user_deactivated_at": null,
    "user_requested_deletion_at": null
  }
}

{
  "data": {
    "id": "UG9kQnVzaW5lc3NSZWNvcmQ6MTQ5",
    "type": "business",
    "external_id": "unique_external_id_456",
    "created_at": "2023-09-01T09:57:23Z",
    "details": {
      "name": "Hooli Ltd",
      "tax_country": "US",
      "tax_id": "12-3456789",
      "secondary_tax_ids": [
        {
          "tax_country": "CA",
          "tax_id": "000-999-000"
        }
      ],
      "us_person": true,
      "principal_location": {
        "address_one": "22 Wall St",
        "address_two": null,
        "city": "New York",
        "region": null,
        "postal_code": "10005",
        "state": "NY",
        "country": "US"
      },
      "business_type": "C Corporation",
      "accreditation_status": null,
      "primary_contact": {
        "id": "UG9kVXNlclJlY29yZDox"
      },
      "control_persons": [
        {
          "id": "UG9kVXNlclJlY29yZDox",
          "title": "CEO"
        }
      ],
      "beneficial_owners": [
        {
          "id": "UG9kVXNlclJlY29yZDox",
          "ownership_percent": 0.25
        }
      ],
      "accreditation_assertion_type": null,
      "indicated_unaccredited_at": null,
      "accreditation_expires_at": null,
      "incorporation_country": null,
      "incorporation_region": null,
      "incorporation_state": null,
      "beneficial_ownership_threshold": null,
      "consistency_summary": {
        "tin_multiple_match": null,
        "possibly_deceased": null,
        "address_records_match_level": null,
        "address_submitter_match": null,
        "name_records_match_level": null,
        "name_tax_match": null,
        "tin_records_match_level": null,
        "overall_records_match_level": null,
        "address_id_match": null,
        "birth_date_id_match": null,
        "birth_date_records_match_level": null,
        "id_validity": null,
        "id_matching_sides": null,
        "name_id_match": null,
        "address_id_value": null,
        "birth_date_id_value": null,
        "id_selfie_similarity_level": null,
        "name_id_value": null,
        "selfie_liveness_probability_level": null,
        "name_tax_value": null
      },
      "change_created_at": "2023-09-01T09:59:10Z",
      "change_created_by": null,
      "change_id": "UG9kQnVzaW5lc3NEYXRhRW50cnk6NDMz",
      "source": "api"
    },
    "traits": [
      {
        "id": "commitment-amount",
        "name": "Commitment Amount",
        "type": "number",
        "value": "500000.25"
      },
      {
        "id": "external-ids",
        "name": "External IDs",
        "type": "strings",
        "value": ["us:12345-67890", "ca:12345-67890"]
      },
      {
        "id": "priority",
        "name": "Priority",
        "type": "string",
        "value": "Medium"
      },
      {
        "id": "refresh-date",
        "name": "Refresh Date",
        "type": "date",
        "value": "2025-05-10"
      },
      {
        "id": "returning-investor",
        "name": "Returning Investor",
        "type": "boolean",
        "value": true
      }
    ],
    "identity_link_established_at": null,
    "archived_at": null,
    "identity_link_expiration_requested_by": null,
    "identity_link_expires_at": null,
    "current_status": {
      "status": "open",
      "notes": null,
      "set_by": null,
      "set_at": "2023-09-01T09:59:10Z"
    }
  }
}