ℹ️ This process can also be used to update Account, Organization, User, Custom Object, 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 updated 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 PUT from the menu options to the left | 
|
Enter this URL in the text field:
| 
|
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/customObjects
EU Data Center:
https://rest.vitally-eu.io/resources/customObjects
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 {{id}} 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.
{
"accountId": "{{Account Vitally ID}}",
"organizationId": "{{Organization External ID}}",
"subject": "{{subject}}",
"note": "{{note}}",
"noteDate": "{{note date}}",
"categoryId": "{{categoryId}}",
"tags": {{tags}}
}You can update any of the variables above, but "tags" is an array, which should be formatted in your CSV as [”tag1”,”tag2”]. Ensure that your CSV uses standard quotation marks, not smart quotation marks, or this process will not work.
⚠️ If you are updating an existing Note that already has tags, you'll need to include any existing tags in the tags array in every row of your CSV.
If you leave the tags array blank in your CSV, all tags will be removed from the Note.
6. Save The PUT Request
Use the disk icon to save this request into a Collection
Enter a name for the Request (e.g., “New Note 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 ID of the Note you’re updating, along with the Subject, Note Body, and Tags. The ID column is required; the other columns will depend on the data you’re updating. Here are more details about what’s required in your PUT request
ℹ️ Anything within the {{variable}} in Postman can map to a CSV column.
Example file (update_notes.csv):
id,Account Vitally ID,subject,note,note date,category,tags 950note-563a-4719-8c93-example1,8e26acc-oun-t43xa-mp13-485a1ec426,This is a Subject,This is the Description body of the Note,2020-12-11T20:16:27.370Z,Note Category,["Tag1","Tag2"]
If copying the example CSV, be sure to replace the values for id with real Note IDs from your own Vitally instance, and replace the tag array values and category with your own.
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
⚠️ If you are updating an existing Note that already has tags, you'll need to include any existing tags in the tags array in every row of your CSV. If you leave the tags array blank in your CSV, all tags will be permanently removed from the Note.
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.
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/...
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.
