Skip to main content

REST API: Bulk POST Requests through Postman

This documentation will guide you through the process of creating new Custom Objects in bulk.

Sharon avatar
Written by Sharon
Updated over a week ago

ℹ️ 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

  1. Click into the Add variable box

  2. Enter subdomain in the Variable column

  3. In 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)

  4. Click into the new Add variable box below subdomain

  5. Enter auth in the Variable column

  6. In the Value column, paste your basic auth header

    1. To locate and copy your basic auth header:

      1. Navigate to the REST API Integration page and ensure the integration is enabled

      2. Hover your cursor over the black box under Basic Auth Header

      3. Click the blue Copy button

      4. If a key is not present, select the blue Create API key button, then follow steps 2 & 3 to copy your auth header

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 POST from the menu options to the left

Enter this URL in the POST request text field: For US-hosted customers:

https://{{subdomain}}.rest.vitally.io/resources/customObjects/:customObjectId/instances

For EU-hosted customers:

https://rest.vitally-eu.io/resources/customObjects/:customObjectId/instances

Enter the :customObjectId in the Params tab

1. Make sure you've selected Params below the request URL

2. In the Path Variables section, you’ll see the Key columns contains customObjectId

3. In the Value column, enter your Custom Object ID

To get the Custom Object ID:

  1. Navigate to Settings > Custom Objects, and select the Custom Object that you’re uploading new instances to

  2. In the URL, copy the slug at the end of the URL, after /custom-objects/

⚠️ If {{subdomain}} in the URL or {{auth}} in the Value column are red, you’ll need to select your Environment in the top right.

4. Add Your Headers

  • Below the request URL, select the Headers tab

    • In the Headers table, enter Content-Type in the Key column and application/json as the Value

    • In a new row, enter Authorization in 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’ll need to select the raw radio button (as shown in the screenshot below) from the options in the Body tab. Your Postman may default to

none.

{   
   "name": "{{name}}",
   "customerId": "{{customerId}}",
   "externalId": "{{externalId}}",
   "traits": {
     "vitally.custom.amount": "{{vitally.custom.amount}}",     
     "vitally.custom.status": "{{vitally.custom.status}}"
   }
}

You can adjust the request body to include any traits that are applicable to your own Vitally environment. In the provided example request body, the trait variables are Amount and Status, and they are listed as their trait keys: "vitally.custom.amount" and "vitally.custom.status". These variables should align with the columns included in your CSV, which is covered in the Prepare a CSV file section.

To define the trait variables in your request body, you’ll put the trait key in double quotes to the left of the colon, and then in double quotes and double curly brackets to the right of the colon. You’ll repeat this formatting in the traits array in your request body for every trait you’re adding to your CSV as a column.

"vitally.custom.amount": "{{vitally.custom.amount}}"

To locate custom object traits in your own Vitally instance, navigate to Settings > Custom Objects and select the Custom Object from the list that you’re working with. Any trait shown here can be used in your request body as a variable. To locate the trait key, select the blue Edit button. The key will be listed first. Select the entire string and paste it into your request body.

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”) 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 a column for the customerId. This is the Vitally ID of the account to which the new custom object instances should be attached. Your CSV should also contain the name of each custom object instance in another column.

If you edited the example request body to define your own trait variables, you’ll need to add a column to your CSV for each trait you defined in the request body. Use the trait Key as the column header in your CSV file. See Step 5 above for details on locating the trait key.

ℹ️ The CSV Header should match each trait's Key exactly.

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

When creating new custom object instances via the API, the customerId needs to be the Vitally ID, and not the External ID. To get the Vitally ID for your customers, you can export an Account or Organization explorer table view. The ID column is included by default.

If you’re familiar with using the REST API, and would prefer to GET the Vitally ID via the REST API, here is a link to our documentation.

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

... menu

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 POST request you saved earlier and uncheck any other boxes

Select the orange Run button. (The button’s name will reflect the name of the collection you’re working in)

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:

  1. Navigate to Settings > Custom Objects, and select the Custom Object that you’re uploading new instances to

  2. In the URL, copy the slug at the end of the URL, after /custom-objects/

Error: Resource not found

Ensure that the column headers in your CSV are exactly the same at the trait key for each trait variable/column.

Related Articles
REST API: Organizations
REST API: Accounts
REST API: Custom Objects
REST API: Bulk PUT Requests through Postman
REST API: Bulk DELETE Requests through Postman
Did this answer your question?