ℹ️ 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)
Click into the new Add variable box below
subdomainEnter
authin the Variable columnIn the Value column, paste your basic auth header
To locate and copy your basic 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
Example Variables:
Variable | Example Value |
subdomain | your-subdomain |
auth | Basic <your_base64_auth> |
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 PUT request text field: For US-hosted customers:
For EU-hosted customers:
| 
|
To get the Note ID:
Navigate to a Notes explorer table
Filter the table to only the Notes to want to update
Export the Notes table to CSV
The ID column will be included automatically in your export
⚠️ If {{subdomain}} in the URL is red, you’ll need to select your Environment in the top right. {{id}} is expected to be red, as this value will come from your CSV.
4. Add Your Headers
Below the request URL, select the Headers tab
In the Headers table, enter
Content-Typein the Key column andapplication/jsonas the ValueIn a new row, enter
Authorizationin the Key column and{{auth}}as the Value
Key | Value |
Content-Type | application/json |
Authorization | {{auth}} |
5. Add the request body (raw JSON)
In the Body tab, enter the example text below at line 1. Include the opening and closing curly brackets. You can include any traits or fields you want.
{
"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”) in the Request name field
Create a new collection, or add to an existing one in the Save to workflow (e.g., “Vitally API Examples”)
Select the orange Save button
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 defined as a variable in your request body can map to a column in your CSV. For example: "categoryId": "{{categoryId}}" defines the Note Category and should hold the Category's ID in your CSV.
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. If you’ve added or removed the defined trait variables from the example request body, you’ll use those trait keys as the column headers instead.
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. On the right side, choose how you want to run your collection. If running this as a one-time event, you’ll likely choose Run manually 2. Under Run configuration > Data file click the Select file button to upload your CSV file and select to run it locally 3. In the middle panel, under Run Sequence, you’ll select the PUT request you saved earlier and uncheck any other boxes 4. Select the orange Run button. (The button’s name will reflect the name of the collection you’re working in) | 
|
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.
