Home / GraphQL API

Using the Highnote API

Request URLs

The URL used for the Highnote API depends on your environment. The endpoint will be /graphql, but the sub-domain will differ.

Test Environment Request URL
https://api.us.test.highnote.com/graphql
Live Environment Request URL
https://api.us.highnote.com/graphql

Authentication

Highnote API requests are authenticated using Basic auth where your API Key is provided as the username. A password is not required. See below for details on obtaining API keys.

To make a request, pass an Authorization header with your base64 encoded API key.

Requests sent with missing or invalid credentials will receive a 401 Unauthorized response code.

Obtaining an API Key

CleanShot 2022-11-30 at 11.08.24@2x.png

You can obtain an API key via the Highnote Dashboard by navigating to API Keys in Developers, and creating a new key. If you don't yet have a Highnote account, you can sign up for one.

The newly generated key will only be presented once and cannot be retrieved later. API keys can be revoked at any time via the Highnote Dashboard.

Auth header
'Authorization': 'Basic <base64_encoded_api_key>'
Example request with Authorization header
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic <base64_encoded_api_key>' \
--data '{"query":"query Ping {\n  ping\n}"}' \
https://api.us.test.highnote.com/graphql

Headers

The Highnote API requires Authorization and Content-Type headers. Since the API accepts and returns JSON, pass a Content-Type header with the value of application/json.

Status Codes

The following HTTP status codes will be returned from the API.

Status CodeScenario
200 OKGraphQL request was successful or validation/logic errors occurred. See error handling for more.
400 Bad RequestGraphQL validation failed. This is generally because of malformed input or selection sets. In this case, the errors collection will be present on the response body.
401 UnauthorizedReturned when invalid credentials are present.
5xxSomething is wrong on the Highnote side.

Response Bodies

Read more about GraphQL responses and formats in the spec.

The Highnote API returns JSON response bodies. The responses will contain the following:

Response BodyDescription
dataThe result of the given operation(s). This data will reflect the shape of your selection on the query.
errorsThe errors collection will be present if the GraphQL engine failed to parse or validate the given request. Read more about errors in the spec.
extensionsThe extensions field is a map of data custom to a GraphQL implementation. For the Highnote API, the extensions field will contain a requestId for use in debugging or support scenarios.

More about troubleshooting with Request IDs in the Highnote API.

Request Body

The Highnote GraphQL API accepts POST requests with JSON payloads. The requests must contain a string named query but can also contain variables and operationName.

query

The query is the GraphQL operation (query, mutation, etc.) that you are calling.

{
  "query": "{ ping }"
}

You can make multiple GraphQL "requests" in a single call. In this case, you would still provide a single query value with all calls as a string.

{
  "query": "query Ping {\n  ping\n  ping2: ping\n}"
}

variables

The variables field is used to pass dynamic input to queries and mutations.

Here is an example of passing variables to the IssuePaymentCard mutation.

mutation IssuePaymentCard($input: IssuePaymentCardInput!) {
  issuePaymentCard(input: $input) {
    ... on PaymentCard {
      id
    }
  }
}

For this mutation, the payload would be created like this:

const payload = JSON.stringify({
  query: `
mutation IssuePaymentCard($input: IssuePaymentCardInput!) {
  issuePaymentCard(input: $input) {
    ... on PaymentCard {
      id
    }
  }
}
`,
  variables: {
    input: {
      cardholderId: "cardholder_id",
      cardProductId: "card_product_id",
      options: {
        activateOnCreate: true,
        expirationDate: "2022-01-01T23:59:59Z",
      },
    },
  },
});

Learn more about using variables in GraphQL.

operationName

In the case that you have a GraphQL document that contains multiple operations, you can use operationName to tell the server which to execute. For example, given the following GraphQL with both IssuePaymentCard and Ping, to run Ping, you would provide HelloWorld as the operationName on your payload:

GraphQL document:

query HelloWorld {
  ping
}

mutation IssuePaymentCard($input: IssuePaymentCardInput!) {
  issuePaymentCard(input: $input) {
    ... on PaymentCard {
      id
    }
  }
}

Payload:

{
  "query": "...",
  "operationName": "HelloWorld"
}

Read more about using operationName here.

Provide Feedback

Was this content helpful?