Skip to main content
Our REST APIs use custom headers for passing context in requests and returning useful metadata in responses. This page documents the headers that are common to all endpoints. Some endpoints may include additional headers specific to their functionality.

​
Request Headers

​
User Context

Our REST APIs are not meant to be called directly by partners’ frontend applications, but rather by partners’ backend systems. A side-effect of this is that Uphold is unable to extract context of users’ requests, such as the user’s IP address, user agent, and other information that would be typically available otherwise. To address this, Uphold provides a way for partners to pass users’ context via headers. This context will be used to enrich the request and provide better insights into end users’ actions. In fact, certain APIs require parts of the context to be present in order to function correctly, so it is highly recommended to include it in all API requests made by partners on behalf of their end users. Partners should include the following headers in their API requests:
  • X-Uphold-User-Ip: The IP address of the end user.
  • X-Uphold-User-Agent: The user agent string of the end user’s device.
  • X-Uphold-User-Origin: The original Origin header if the request was made from a browser.
  • X-Uphold-User-Country: The country code (ISO 3166 - two letter) associated with the geolocation of the end user.
  • X-Uphold-User-Subdivision: The subdivision code (ISO 3166) associated with the geolocation of the end user.
  • X-Uphold-User-City: The city associated with the geolocation of the end user.

​
Response Headers

​
Request Id

Every API response includes an X-Uphold-Request-Id header containing a unique identifier for the request. Partners can use this identifier when contacting Uphold support to help troubleshoot specific requests. 
X-Uphold-Request-Id: 9d71b4edeb46c8f9-MAD