This is unreleased documentation for Parallel Developer Documentation **Next 🚧** version. For up-to-date documentation, see the **[latest version](https://developer.parallelmarkets.com/docs/server/case-management-api/records/create)** (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](https://en.wikipedia.org/wiki/E.164) format with a country code prefix (i.e., "+12121234567"). | | `birth_date` _(string)_ | _Optional._ String `YYYY-MM-DD` [date](https://developer.parallelmarkets.com/docs/next/server/data-structures#dates-and-timestamps) 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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) 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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes representing the individuals secondary countries of citizenship. | | `tax_country` _(string)_ | _Optional._ [ISO Alpha-2 Country Code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) 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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements).
- `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](https://developer.parallelmarkets.com/docs/next/server/data-structures#location) object representing the individual's residence address. | | `domicile_location` _(object)_ | _Optional._ A [Location](https://developer.parallelmarkets.com/docs/next/server/data-structures#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](https://developer.parallelmarkets.com/docs/next/server/case-management-api/records/create/#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](https://developer.parallelmarkets.com/docs/next/server/case-management-api/records/create/#setting-record-trait-values) for more information. | #### Sample payload ```json { "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](https://developer.parallelmarkets.com/docs/next/server/data-structures#business-profile) for possible values. | | `incorporation_country` _(string)_ | _Optional._ [ISO Alpha-2 Country Code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) 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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) 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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements).
- `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](https://developer.parallelmarkets.com/docs/next/server/data-structures#location) object representing where the business primarily conducts its business. | | `domicile_location` _(object)_ | _Optional._ A [Location](https://developer.parallelmarkets.com/docs/next/server/data-structures#location) object representing the business's legal domicile. | | `external_id` _(string)_ | _Optional._ A custom unique identifier for this record. See [Using an External Identifier](https://developer.parallelmarkets.com/docs/next/server/case-management-api/records/create/#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](https://developer.parallelmarkets.com/docs/next/server/case-management-api/records/create/#setting-record-trait-values) for more information. | ```json { "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 } } ``` ```json { "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](https://developer.parallelmarkets.com/docs/next/server/data-structures#record) 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](https://developer.parallelmarkets.com/docs/next/server/case-management-api/records/create/#request-parameters) or [updating a record](https://developer.parallelmarkets.com/docs/next/server/case-management-api/records/update). 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](https://developer.parallelmarkets.com/docs/next/server/data-structures#record) support the ability to store additional information about an individual or business record using preconfigured [Record Traits](https://developer.parallelmarkets.com/docs/next/server/data-structures#record-trait). 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. | 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](https://support.parallelmarkets.com/hc/en-us/articles/32394559104397-Record-Traits). 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.