Open a tap intent

curl --request POST \
  --url https://api2.endstate.io/v1/tap-intents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "rule": "own",
  "unit_id": "6f1d2c3b-4a59-4e68-9f70-8a1b2c3d4e5f",
  "action": {
    "type": "listing.confirm",
    "reference": "listing_8271"
  },
  "redirect_url": "https://app.example.com/listings/8271/confirm",
  "display": {
    "title": "Confirm your listing"
  }
}
'

import requests

url = "https://api2.endstate.io/v1/tap-intents"

payload = {
    "rule": "own",
    "unit_id": "6f1d2c3b-4a59-4e68-9f70-8a1b2c3d4e5f",
    "action": {
        "type": "listing.confirm",
        "reference": "listing_8271"
    },
    "redirect_url": "https://app.example.com/listings/8271/confirm",
    "display": { "title": "Confirm your listing" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    rule: 'own',
    unit_id: '6f1d2c3b-4a59-4e68-9f70-8a1b2c3d4e5f',
    action: {type: 'listing.confirm', reference: 'listing_8271'},
    redirect_url: 'https://app.example.com/listings/8271/confirm',
    display: {title: 'Confirm your listing'}
  })
};

fetch('https://api2.endstate.io/v1/tap-intents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api2.endstate.io/v1/tap-intents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'rule' => 'own',
    'unit_id' => '6f1d2c3b-4a59-4e68-9f70-8a1b2c3d4e5f',
    'action' => [
        'type' => 'listing.confirm',
        'reference' => 'listing_8271'
    ],
    'redirect_url' => 'https://app.example.com/listings/8271/confirm',
    'display' => [
        'title' => 'Confirm your listing'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api2.endstate.io/v1/tap-intents"

	payload := strings.NewReader("{\n  \"rule\": \"own\",\n  \"unit_id\": \"6f1d2c3b-4a59-4e68-9f70-8a1b2c3d4e5f\",\n  \"action\": {\n    \"type\": \"listing.confirm\",\n    \"reference\": \"listing_8271\"\n  },\n  \"redirect_url\": \"https://app.example.com/listings/8271/confirm\",\n  \"display\": {\n    \"title\": \"Confirm your listing\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api2.endstate.io/v1/tap-intents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"rule\": \"own\",\n  \"unit_id\": \"6f1d2c3b-4a59-4e68-9f70-8a1b2c3d4e5f\",\n  \"action\": {\n    \"type\": \"listing.confirm\",\n    \"reference\": \"listing_8271\"\n  },\n  \"redirect_url\": \"https://app.example.com/listings/8271/confirm\",\n  \"display\": {\n    \"title\": \"Confirm your listing\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api2.endstate.io/v1/tap-intents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"rule\": \"own\",\n  \"unit_id\": \"6f1d2c3b-4a59-4e68-9f70-8a1b2c3d4e5f\",\n  \"action\": {\n    \"type\": \"listing.confirm\",\n    \"reference\": \"listing_8271\"\n  },\n  \"redirect_url\": \"https://app.example.com/listings/8271/confirm\",\n  \"display\": {\n    \"title\": \"Confirm your listing\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "tapi_3f9c1b7a2d4e4f60a1b2c3d4e5f60718",
  "status": "pending",
  "rule": "own",
  "unit_id": "6f1d2c3b-4a59-4e68-9f70-8a1b2c3d4e5f",
  "action": {
    "type": "listing.confirm",
    "reference": "listing_8271"
  },
  "redirect_url": "https://app.example.com/listings/8271/confirm",
  "display": {
    "title": "Confirm your listing"
  },
  "code_required": true,
  "scan": null,
  "created_at": "2026-11-10T17:02:11.000Z",
  "expires_at": "2026-11-10T17:07:11.000Z",
  "approved_at": null,
  "use_by": null,
  "consumed_at": null,
  "canceled_at": null,
  "tap_code": "482913"
}

Tap intents

Open a tap intent

Opens a tap intent for one unit, so a person can confirm a step in your app by tapping the item with any phone. The response carries tap_code to show the person. They tap the item, the page the tap opens lists the unit’s open tap intents, and they confirm this one there with the code. The tap intent is then approved and Endstate sends tap_intent.approved. Consume it within use_within seconds of the approval, then perform your own action. A unit can have up to 10 open tap intents. Tap intents must be enabled for the environment.

POST

tap-intents

Open a tap intent

curl --request POST \
  --url https://api2.endstate.io/v1/tap-intents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "rule": "own",
  "unit_id": "6f1d2c3b-4a59-4e68-9f70-8a1b2c3d4e5f",
  "action": {
    "type": "listing.confirm",
    "reference": "listing_8271"
  },
  "redirect_url": "https://app.example.com/listings/8271/confirm",
  "display": {
    "title": "Confirm your listing"
  }
}
'

import requests

url = "https://api2.endstate.io/v1/tap-intents"

payload = {
    "rule": "own",
    "unit_id": "6f1d2c3b-4a59-4e68-9f70-8a1b2c3d4e5f",
    "action": {
        "type": "listing.confirm",
        "reference": "listing_8271"
    },
    "redirect_url": "https://app.example.com/listings/8271/confirm",
    "display": { "title": "Confirm your listing" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    rule: 'own',
    unit_id: '6f1d2c3b-4a59-4e68-9f70-8a1b2c3d4e5f',
    action: {type: 'listing.confirm', reference: 'listing_8271'},
    redirect_url: 'https://app.example.com/listings/8271/confirm',
    display: {title: 'Confirm your listing'}
  })
};

fetch('https://api2.endstate.io/v1/tap-intents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api2.endstate.io/v1/tap-intents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'rule' => 'own',
    'unit_id' => '6f1d2c3b-4a59-4e68-9f70-8a1b2c3d4e5f',
    'action' => [
        'type' => 'listing.confirm',
        'reference' => 'listing_8271'
    ],
    'redirect_url' => 'https://app.example.com/listings/8271/confirm',
    'display' => [
        'title' => 'Confirm your listing'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api2.endstate.io/v1/tap-intents"

	payload := strings.NewReader("{\n  \"rule\": \"own\",\n  \"unit_id\": \"6f1d2c3b-4a59-4e68-9f70-8a1b2c3d4e5f\",\n  \"action\": {\n    \"type\": \"listing.confirm\",\n    \"reference\": \"listing_8271\"\n  },\n  \"redirect_url\": \"https://app.example.com/listings/8271/confirm\",\n  \"display\": {\n    \"title\": \"Confirm your listing\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api2.endstate.io/v1/tap-intents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"rule\": \"own\",\n  \"unit_id\": \"6f1d2c3b-4a59-4e68-9f70-8a1b2c3d4e5f\",\n  \"action\": {\n    \"type\": \"listing.confirm\",\n    \"reference\": \"listing_8271\"\n  },\n  \"redirect_url\": \"https://app.example.com/listings/8271/confirm\",\n  \"display\": {\n    \"title\": \"Confirm your listing\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api2.endstate.io/v1/tap-intents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"rule\": \"own\",\n  \"unit_id\": \"6f1d2c3b-4a59-4e68-9f70-8a1b2c3d4e5f\",\n  \"action\": {\n    \"type\": \"listing.confirm\",\n    \"reference\": \"listing_8271\"\n  },\n  \"redirect_url\": \"https://app.example.com/listings/8271/confirm\",\n  \"display\": {\n    \"title\": \"Confirm your listing\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "tapi_3f9c1b7a2d4e4f60a1b2c3d4e5f60718",
  "status": "pending",
  "rule": "own",
  "unit_id": "6f1d2c3b-4a59-4e68-9f70-8a1b2c3d4e5f",
  "action": {
    "type": "listing.confirm",
    "reference": "listing_8271"
  },
  "redirect_url": "https://app.example.com/listings/8271/confirm",
  "display": {
    "title": "Confirm your listing"
  },
  "code_required": true,
  "scan": null,
  "created_at": "2026-11-10T17:02:11.000Z",
  "expires_at": "2026-11-10T17:07:11.000Z",
  "approved_at": null,
  "use_by": null,
  "consumed_at": null,
  "canceled_at": null,
  "tap_code": "482913"
}

Authorizations

Authorization

string

header

required

Use Authorization: Bearer end_sk_* for partner API keys (e.g. end_sk_AbCd_example_api_key).

Headers

Idempotency-Key

string

Unique key that makes this request safe to retry. Replaying the key with the same body returns the original response with Idempotent-Replayed: true; replaying it with a different body returns 409 idempotency.key_conflict.

Required string length: 1 - 255

Example:

"a1b2c3d4-0000-4000-8000-000000000000"

Body

application/json

rule

enum<string>

required

Who may open the intent. own opens it on a unit in your own environment.

Available options:

own

unit_id

string<uuid>

required

The unit the person will tap.

action

object

required

Opaque to Endstate. Stored with surrounding whitespace trimmed, returned on reads and in webhooks, and compared exactly when you consume.

Show child attributes

ttl

integer

default:300

Seconds the intent waits for a tap. A tap after that does not count.

Required range: 60 <= x <= 900

use_within

integer

default:300

Seconds after the person approves in which you can consume the approval. Fixed here: use_by is approved_at plus this, and no call extends it.

Required range: 60 <= x <= 900

code

boolean

default:true

Whether the person must enter a code to confirm. On by default: the response carries tap_code for you to show them. Pass false only where the person asking is the person holding the item and a wrong approval costs little, because anyone who taps the item can then confirm.

redirect_url

string

Where the person is sent after they confirm. tap_intent=<id> is added to it. Must be on one of the environment's allowed origins.

Maximum string length: 2048

Example:

"https://app.example.com/listings/8271/confirm"

display

object

Show child attributes

Response

The open tap intent and its code.

string

required

status

enum<string>

required

pending until the person confirms. approved once they have: consume it by use_by. consumed once you have used the approval; it is used once. canceled ended without an approval. expired means nobody approved in time, or the approval was not consumed by use_by. consumed and canceled are final. Approving, canceling and consuming each send a webhook; expiring sends none.

Available options:

pending,

approved,

consumed,

canceled,

expired

rule

enum<string>

required

Available options:

own

unit_id

string<uuid>

required

action

object

required

Show child attributes

redirect_url

string | null

required

display

object

required

Show child attributes

code_required

boolean

required

Whether the person must enter the code to confirm.

scan

object | null

required

The tap the intent was approved with. Null until it is approved.

Show child attributes

created_at

string<date-time>

required

expires_at

string<date-time>

required

A tap must arrive by this time. The person can confirm for 10 minutes after their tap.

approved_at

string<date-time> | null

required

When the person approved. Kept on an approval that expired unused.

use_by

string<date-time> | null

required

The approval can be consumed until this time: approved_at plus the use_within set at create. Null until approved.

consumed_at

string<date-time> | null

required

When you consumed the approval. Null until then.

canceled_at

string<date-time> | null

required

tap_code

string | null

required

The six digit code to show the person, or null when code is false. Returned by this response only: no read or webhook carries it, and a replay of the same Idempotency-Key returns null. If you lose it, cancel and open a new tap intent.

Example:

"482913"

Overview

Endpoints

Open a tap intent

Authorizations

Headers

Body

Response