Create a record | Parallel Developer Documentation

This is unreleased documentation for Parallel Developer Documentation Next 🚧 version.

For up-to-date documentation, see the latest version (Current – v2.x).

Version: Next 🚧

On this page

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:

Individual: POST https://api.parallelmarkets.com/v2/partner-records/individuals
Business: POST https://api.parallelmarkets.com/v2/partner-records/businesses

Request Parameters

Individual Record
Business Record

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 (includes but is not limited to a partnership, corporation, company or association created or organized in the United States or under the laws of the United States; any estate (other than a foreign estate); or a domestic trust).
`primary_contact` (object)	Optional. An object containing the following keys: - `id`: The ID of the individual record associated with the primary contact. Note: In order to pass in a primary contact when creating a business record, the individual primary contact record must first be created in order to correctly set the `id` here.
`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`. Note: In order to pass in control persons when creating a business record, the individual control person records must first be created in order to correctly set the `id` here.
`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` (25%). Note: In order to pass in beneficial owners when creating a business record, the individual or business records for each beneficial owner must first be created in order to correctly set the `id` here.
`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. See Setting Record Trait Values for more information.

{

"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"
  },

### Response Parameters

Returns a [Record](https://developer.parallelmarkets.com/docs/next/server/data-structures#record) after successful record creation.

### Example Response

- Individual Record
- Business Record

```json
{

"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": "UG9kVXNlclJlY29yZDox",

"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"

},

"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"
    }

}
}

Using an External Identifier

Case Management Records support an external_id attribute that can be set with a custom value. This is useful when you want to identify a Parallel record with a unique ID from one of your systems, for example, an identifier from a CRM or your own database.

An external_id can be set for a record when creating a record or updating a record.

If provided, the external_id can be used in place of the Parallel system-generated ID when making queries or operations against the API.

caution

The external_id associated with a record must be unique across all individual and business records within your Case Management account. Providing an external_id that is already associated with another record will remove that same ID from the previous record (the external_id will be set to null).

Setting Record Trait Values

Case Management Records support the ability to store additional information about an individual or business record using preconfigured Record Traits. Each trait can be used to store custom data about the record.

note

We do not currently support programmatically configuring traits via the API. Traits can be configured in your partner dashboard.

When creating a record, you can include an array of traits within the record creation payload. Each trait object should contain the following parameters:

Parameter Description

id (string) Required The ID of the record trait.

value (string or string[] or boolean) Required The value of the record trait.
Note: The value must match the expected type for the trait (e.g., a string for a trait of type string, an array of strings for a trait of type strings, a boolean for a trait of type boolean, etc.). There are two notable exceptions to this rule:
- Use a string for a trait of type date.
- Use a string for a trait of type number to ensure proper storage of decimal values.

Parameter	Description
`id` (string)	Required The ID of the record trait.
`value` (string or string[] or boolean)	Required The value of the record trait. Note: The value must match the expected type for the trait (e.g., a string for a trait of type `string`, an array of strings for a trait of type `strings`, a boolean for a trait of type `boolean`, etc.). There are two notable exceptions to this rule: - Use a `string` for a trait of type `date`. - Use a `string` for a trait of type `number` to ensure proper storage of decimal values.

note

For traits of type string and strings, you can define a list of acceptable values in your partner dashboard. These traits will only accept values from the predefined list, and any other values will result in an error. For more information on configuring record traits, please refer to the partner support page.

note

If you don't want to set or modify a value for a certain trait, omit the trait from the traits array. Omitting the whole trait parameter from the payload will leave all configured trait values unset (or unmodified) for the record.