Push installations

Register a push installation

POST/v1/contacts/{id}/installations

Requires an API key with the contacts:write scope. About keys and scopes

Registers a device or browser subscription against a contact so push can reach it. Re-registering the same token updates the existing installation rather than creating a duplicate.

Path parameters

idstringrequired: uuid

Returns

Returns 200 OK with a PushInstallation in data. Otherwise returns an error; Errors lists every code and which to retry.

idstringrequired

uuid

contactIdstringrequired

uuid

pushAppIdstringrequired

uuid

externalInstallationIdstringrequired

Your own id for the device, as registered.

platformstringrequired

one of ios, android, web

environmentstringrequired

one of sandbox, production

permissionstringrequired

one of granted, denied

activebooleanrequired

False once the device is disabled or its token is refused.

invalidatedAtstring | nullrequired

When the provider refused the token or the device was disabled.

date-time

lastSeenAtstringrequired

When the device last registered or refreshed.

date-time

sdkstring | nullrequired

The Kirora SDK and version that last registered it; null from a server.

createdAtstringrequired

date-time

curl -X POST https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/installations \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pushAppId": "018f2a4e-6b1c-7d3e-9f40-7967f0395a6b",
    "externalInstallationId": "externalInstallationId_example",
    "permission": "granted",
    "targetKind": "apns_token",
    "target": "target_example"
  }'

const response = await fetch('https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/installations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "pushAppId": "018f2a4e-6b1c-7d3e-9f40-7967f0395a6b",
    "externalInstallationId": "externalInstallationId_example",
    "permission": "granted",
    "targetKind": "apns_token",
    "target": "target_example"
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/installations",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "pushAppId": "018f2a4e-6b1c-7d3e-9f40-7967f0395a6b",
        "externalInstallationId": "externalInstallationId_example",
        "permission": "granted",
        "targetKind": "apns_token",
        "target": "target_example",
    },
)
data = response.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "pushAppId": "018f2a4e-6b1c-7d3e-9f40-7967f0395a6b",
	  "externalInstallationId": "externalInstallationId_example",
	  "permission": "granted",
	  "targetKind": "apns_token",
	  "target": "target_example"
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/installations", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

Response · 200

{
  "data": {
    "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
    "contactId": "018f2a4e-6b1c-7d3e-9f40-4db757ce5a6b",
    "pushAppId": "018f2a4e-6b1c-7d3e-9f40-7967f0395a6b",
    "externalInstallationId": "externalInstallationId_example",
    "platform": "ios",
    "environment": "sandbox",
    "permission": "granted",
    "active": true,
    "invalidatedAt": "2030-03-14T09:30:00Z",
    "lastSeenAt": "2030-03-14T09:30:00Z",
    "sdk": "sdk_example",
    "createdAt": "2030-03-14T09:30:00Z"
  }
}

Example values are generated from the schema.