Set the return origins

PUThttps://app.booksbyinstant.com/api/integrator/v1/return-origins

Replaces the list of return origins; [] clears it. The same origins again, in any order, are a 200 that changes nothing.

setReturnOrigins · This page as markdown

Example request

cURL

curl -X PUT 'https://app.booksbyinstant.com/api/integrator/v1/return-origins' \
  -H "Authorization: Bearer $INTEGRATOR_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{
  "origins": [
    "string"
  ]
}'

JavaScript

// Node 18 or later, in an ES module (.mjs), which allows the top-level await.
const res = await fetch("https://app.booksbyinstant.com/api/integrator/v1/return-origins", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.INTEGRATOR_CREDENTIAL}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "origins": [
      "string"
    ]
  }),
});
const data = await res.json();

Python

import os
import requests

res = requests.put(
    "https://app.booksbyinstant.com/api/integrator/v1/return-origins",
    headers={
        "Authorization": f"Bearer {os.environ['INTEGRATOR_CREDENTIAL']}",
    },
    json={
        "origins": [
            "string",
        ],
    },
)
data = res.json()

Authorization

Bearer token live_<100 hex>

Authorization: Bearer <secret>. A 401 answers WWW-Authenticate: Bearer realm="instant-integrator-api".

Request body

At most 4096 bytes.

Body application/json, required

object

no other fields

origins array of string required

Up to ten origins your return URLs may be on, none twice, each exactly as a browser writes it: the scheme, the host in lower case, and the port only when it is not the scheme's default, with no path and no trailing slash. https, or http on a loopback address on your own machine. The return URL's own origin counts as registered without being listed. [] clears the list.

at most 10 items · no repeated items

Example, built from the schema

{
  "origins": [
    "string"
  ]
}

Responses

200

The return origins, sorted.

Body application/json

object

returnOrigins array of string required

Each origin as a browser writes it.

Example, built from the schema

{
  "returnOrigins": [
    "string"
  ]
}

400

The body is not one JSON object, or a field is invalid; error says which.

Body application/json

object Error

Every answer that is not a success.

error string required

Instant's sentence for people. A 4xx keeps the refusal's own sentence; a 5xx always says "Instant is temporarily unavailable. Please try again shortly."
code string required

Stable, and what a caller branches on: VALIDATION_ERROR (400), UNAUTHENTICATED (401), FORBIDDEN (403), NOT_FOUND (404), CONFLICT (409), LIMIT_EXCEEDED (413), UNSUPPORTED_MEDIA_TYPE (415), UNREADABLE_FILE (422), RATE_LIMITED (429) and UNAVAILABLE (5xx). More codes may be added; treat one you do not know by its status.
retryAfter integer

Seconds to wait before retrying, also sent as the Retry-After header. Present only when there is a wait, as on a 429.

at least 1
existingId string · uuid

On a 409 that names the object already there, such as a customer with that reference: its id.

Example, built from the schema

{
  "error": "string",
  "code": "VALIDATION_ERROR",
  "retryAfter": 1,
  "existingId": "01900000-0000-7000-8000-000000000000"
}

401

The credential is missing, malformed, unknown, revoked or rotated, or its integrator is disabled. All of these answer the same way.

Headers

WWW-Authenticate string

Bearer realm="instant-integrator-api"

Body application/json

The Error object, as in 400.

413

The body is over 4096 bytes.

Body application/json

The Error object, as in 400.

415

The body is not sent as application/json.

Body application/json

The Error object, as in 400.

5XX

Instant is temporarily unavailable. Retry later, with backoff.

Body application/json

The Error object, as in 400.