Tech Note: Can I use the API to create new visitor and account records in Pendo?

UPDATE: 

This Tech Note is no longer being updated. There are two methods to create new visitor and account records in Pendo (even if they haven't used your application yet). Please refer to these resources instead:

1. API documentation on using the query parameter ?create=true via the metadata endpoint.
2. Adding/updating custom metadata via CSV upload. If you include a visitor ID or account ID that doesn't. currently exist in Pendo, a new record will be created.

-------------------------------

Consider the use case - is it really necessary?

For 99% of situations, it is not necessary to create visitor & account records in Pendo via the API. This is because Pendo will automatically create the relevant visitor and account records when the individual uses your product. As a reminder, the Pendo agent is automatically collecting product usage analytics and sending those events to Pendo. As Pendo receives those events, the visitor record & account record are automatically created in Pendo.

Please also keep in mind that most of Pendo’s reporting & analytics capabilities are based on product usage. So please carefully consider your project goals and confirm that it’s worth the effort to create visitor & account records in Pendo before any usage data has been collected.

There are some limited situations where you may find value in creating visitor & account records. If you fall into this situation, please continue reading.

Send a modified metadata update request

We will be using an the metadata endpoint, but adding a query parameter of ?create=true. 

Please note that all examples below use the Pendo US instance endpoints of https://app.pendo.io. If your subscription is in the Pendo EU instance, you will need to use https://app.eu.pendo.io instead.  

To create a visitor ID:
POST https://app.pendo.io/api/v1/metadata/visitor/custom/value?create=true

To create an account ID: 
POST https://app.pendo.io/api/v1/metadata/account/custom/value?create=true

Please follow the format of the examples under:  https://engageapi.pendo.io/#bd14400e-0ff9-49e6-932e-61e7a65c6f3c

Example request

POST https://app.pendo.io/api/v1/metadata/visitor/custom/value?create=true

[
    {
        "visitorId": "October-Angela",
        "values": {
            "department": "Marketing",
            "role": "Admin"
        }
    }
]

POST https://app.pendo.io/api/v1/metadata/account/custom/value?create=true

[
    {
        "accountId": "October",
        "values": {
            "subscription_status": "active",
            "industry": "Textiles"
        }
    }
]

What to expect afterwards

The visitor or account record will be created in Pendo with only the metadata values sent in the request. The metadata fields will be created as custom metadata fields. Learn more about metadata here: Visitor & Account Metadata.

There will be no connection between a visitor and account record until Pendo receives an event with both that visitor ID and account ID. 

The newly created visitor (and account) records will have no ‘First Visit’ or ‘Last Visit’ date until Pendo receives an event for that visitor (or account). 

The newly created visitor (and account) records will not appear in Pendo reports since they won't have any events.

By default, they will not appear in tables such as Pendo > People > Visitors (or Pendo > People > Accounts). However, if you see a checkbox option for 'Show all visitors, including those with no events in the selected date range', you will be able to see the visitor records without events. This is true for account tables as well.

You will only be able to find the visitor or account records if you search for them in the search bar.