ℹ️ This process can also be used to create Account, Organization, User, Note, Project, and Task records in bulk using the REST API with Postman’s Collection Runner and a CSV file.
Accounts, Organizations, and Users can also be created in bulk via the CSV upload tool. Here’s more information on that process.
For more information on Postman, including installation instructions and account setup, please review their customer-facing documentation.
Set Up Your Postman Environment
1. Create a new Environment
On the left-hand sidebar, select Environments
Select the + to create a new environment
Name your new environment
2. Define your Variables
Click into the Add variable box
Enter
subdomainin the Variable columnIn the Value column, enter your subdomain. You can find your subdomain in the URL used to log into Vitally (i.e., https://yoursubdomain.vitally.io)
Repeat these steps to add
authalong with your REST API authentication header
Example Variables:
Variable | Example Value |
subdomain | your-subdomain |
auth | Basic <your_base64_auth> |
To copy your auth header:
Navigate to the REST API Integration page and ensure the integration is enabled
Hover your cursor over the black box under Basic Auth Header
Click the blue Copy button
If a key is not present, select the blue Create API key button, then follow steps 2 & 3 to copy your auth header
The Authorization header format is basic auth, using the API Key as the username.
Authorization: Basic c2VjcmV0X2tleTo=
ℹ️ For security purposes, keys can be rolled (a new key will be generated) or deleted.
3. Create a New Request
How To | How To Visual |
Use the + sign at the top to Create New Request | 
|
Select POST from the menu options to the left | 
|
Enter this URL in the text field:
| 
|
Enter the | 
|
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/customObjects
EU Data Center:
https://rest.vitally-eu.io/resources/customObjects
To get the Custom Object ID:
Navigate to Settings > Custom Objects, and select the Custom Object that you’re uploading new instances to
In the URL, copy the slug at the end of the URL, after
/custom-objects/
4. Add Your Headers
Below the URL, select the Headers tab
Create two new headers with the information below:
Key | Value |
Content-Type | application/json |
Authorization | {{auth}} |
⚠️ If {{subdomain}} in the URL or {{auth}} in the Value column are red, you’ll need to select your Environment in the top right
5. Add the request body (raw JSON)
In the Body tab, enter the text below at line 1. You can include any traits or fields you want. Review our REST API documentation for additional details on including traits in your request.
{
"name": "{{name}}",
"customerId": "{{customerId}}",
"externalId": "{{externalId}}",
"traits": {
"vitally.custom.amount": "{{vitally.custom.amount}}",
"vitally.custom.status": "{{vitally.custom.amount}}"
}
}
6. Save The POST Request
Use the disk icon to save this request into a Collection
Enter a name for the Request (e.g., “New Custom Object Demo”)
Create a new collection, or add to an existing one in the save workflow (e.g., “Vitally API Examples”)
Prepare a CSV file
You’ll need a CSV file that contains the External ID of the account the new object instances should attach to, along with the name of each object instance, and values for each account. To update existing traits, you’ll want to use the trait Key assigned in Settings as the column header in your CSV file.
ℹ️ Anything within the {{variable}} in Postman can map to a CSV column.
Example file (create_custom_objects.csv):
name,customerId,externalId,vitally.custom.amount,vitally.custom.status example object 1,xxxxx-xxx-xxxx-xxxx1,custom-object-id-001,400,closed example object 2,xxxx-xxxxx-xxxxx-xxxxx2,custom-object-id-002,550,pending example object 3,xxxx-xxxxx-xxxx-xxxxx3,custom-object-id-003,300,open
If copying the example CSV, be sure to replace the values for customerId with real IDs from your own Vitally instance.
The customerId needs to be the Vitally ID, and not the External ID. You can use the REST API to GET the ID for the account. Here are additional details for this process.
Run a Bulk Request
Postman will iterate through each row of your CSV and plug the CSV values into your request body’s variables, then send each request as an individual API call. Once the collection has completed its run, you’ll see the status codes, response bodies, and any failures. Failures can happen if traits or fields don’t have a match. You can export the run log if needed.
Open the Collection Runner
How To | How To Visual |
1. On the left-hand sidebar in Postman, select Collections 2. Hover the cursor over your new Collection and click the
3. Select Run from the menu options | 
|
1. At the top right, select your new environment from the drop-down menu: it likely says No Environment 2. Pin the environment to the Collection | 
|
1. Select how you want to run your collection; you’ll likely choose Run manually 2. Select your Run Sequence by checking and unchecking boxes 3. Under Data, click the Select file button to upload your CSV file: Choose whether you want to run it locally or upload it as test data to reuse 4. Select the Run button | 
|
Tips and Common Issues
Unexpected characters in your request URL
Copying and pasting the request URL from another source will often add a carriage return. If you’re getting a 404 Not found error when running the Collection, check your URL for stray characters.
Invalid trait key or custom field not found
If you’re encountering an error, such as an invalid trait key or a custom field not found, ensure the keys within "traits" in your request body match the trait API keys in Vitally Trait Settings. These may be different than your CSV header names.
Confirm that the Subdomain matches your workspace
For US-hosted customers: https://{{subdomain}}.rest.vitally.io/resources/...
For EU-hosted customers, you do not need a {{subdomain}}, but ensure you're using the EU-endpoint: https://rest.vitally-eu.io/resources/...
Error: Custom object with id not found
If you're seeing the error "error": "Custom object with id not found”, double-check the Custom Object ID that you entered in your request URL. There may be an extra return or space character, or you may have copied the incorrect part of the URL. You can find your Custom Object ID here:
Navigate to Settings > Custom Objects, and select the Custom Object that you’re uploading new instances to
In the URL, copy the slug at the end of the URL, after
/custom-objects/
