Agent

GET /api/v1/agent/resolve-pin

Resolve a VayaPin ID to its full delivery payload

Return GPS + structured address + business data for pin_id.

404 — the pin does not exist, or it exists but has no active subscription (data_set is None); a name with no live data is not deliverable, so we surface it as not-found rather than a 200 empty body.
500 — our cs-api credential is misconfigured (our bug, not the caller's); logged loud for alerting.
503 — cs-api is temporarily unavailable (5xx / timeout / network).

Parameters

pin_id string query required

VayaPin in COUNTRY:NAME format (both upper-case), e.g. BB:TAPAS887. Mixed case is rejected.

Responses

200Successful Response
422Validation Error

GET /api/v1/agent/resolve-pin

curl -X GET 'https://api.example.com/api/v1/agent/resolve-pin' \
  -H 'Authorization: Bearer '

import httpx

resp = httpx.get(
    "https://api.example.com/api/v1/agent/resolve-pin",
    headers={"Authorization": "Bearer "},
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.example.com/api/v1/agent/resolve-pin", {
  method: "GET",
  headers: { "Authorization": "Bearer " }
});
const data = await resp.json();
console.log(data);

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.example.com/api/v1/agent/resolve-pin", nil)
	req.Header.Set("Authorization", "Bearer ")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

POST /api/v1/agent/search-pins

Search VayaPins by query / filter / facets (Meilisearch-backed)

Forward a Meilisearch-shaped search body to cs-api and return the result.

400 — cs-api rejected the search body as invalid (e.g. a malformed filter / sort expression).
500 — our cs-api credential is misconfigured (our bug); logged loud.
503 — cs-api is temporarily unavailable (5xx / timeout / network).

Responses

200Successful Response
422Validation Error

POST /api/v1/agent/search-pins

curl -X POST 'https://api.example.com/api/v1/agent/search-pins' \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{
  "q": "string",
  "filter": "string",
  "limit": 0,
  "offset": 0,
  "sort": [
    "string"
  ],
  "hitsPerPage": 0,
  "page": 0,
  "facets": [
    "string"
  ],
  "attributesToRetrieve": [
    "string"
  ]
}'

import httpx

resp = httpx.post(
    "https://api.example.com/api/v1/agent/search-pins",
    headers={"Authorization": "Bearer ", "Content-Type": "application/json"},
    json={"q": "string", "filter": "string", "limit": 0, "offset": 0, "sort": ["string"], "hitsPerPage": 0, "page": 0, "facets": ["string"], "attributesToRetrieve": ["string"]},
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.example.com/api/v1/agent/search-pins", {
  method: "POST",
  headers: { "Authorization": "Bearer ", "Content-Type": "application/json" },
  body: JSON.stringify({"q": "string", "filter": "string", "limit": 0, "offset": 0, "sort": ["string"], "hitsPerPage": 0, "page": 0, "facets": ["string"], "attributesToRetrieve": ["string"]})
});
const data = await resp.json();
console.log(data);

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"q": "string", "filter": "string", "limit": 0, "offset": 0, "sort": ["string"], "hitsPerPage": 0, "page": 0, "facets": ["string"], "attributesToRetrieve": ["string"]}`)
	req, _ := http.NewRequest("POST", "https://api.example.com/api/v1/agent/search-pins", body)
	req.Header.Set("Authorization", "Bearer ")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Request body

{"q":"string","page":0,"sort":["string"],"limit":0,"facets":["string"],"filter":"string","offset":0,"hitsPerPage":0,"attributesToRetrieve":["string"]}

POST /api/v1/agent/preview-pin

Suggest available VayaPin names for a user

Check whether body.name is an available VayaPin in body.country_code.

200 — is_available true with empty suggestions (name free), or false with up to count alternative names (name taken).
502 — cs-api returned a body we could not interpret (a contract mismatch on our side, not the caller's); logged for alerting.
500 — our cs-api credential is misconfigured (our bug); logged loud.
503 — cs-api is temporarily unavailable (5xx / timeout / network).

Responses

200Successful Response
422Validation Error

POST /api/v1/agent/preview-pin

curl -X POST 'https://api.example.com/api/v1/agent/preview-pin' \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "country_code": "string",
  "count": 5
}'

import httpx

resp = httpx.post(
    "https://api.example.com/api/v1/agent/preview-pin",
    headers={"Authorization": "Bearer ", "Content-Type": "application/json"},
    json={"name": "string", "country_code": "string", "count": 5},
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.example.com/api/v1/agent/preview-pin", {
  method: "POST",
  headers: { "Authorization": "Bearer ", "Content-Type": "application/json" },
  body: JSON.stringify({"name": "string", "country_code": "string", "count": 5})
});
const data = await resp.json();
console.log(data);

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"name": "string", "country_code": "string", "count": 5}`)
	req, _ := http.NewRequest("POST", "https://api.example.com/api/v1/agent/preview-pin", body)
	req.Header.Set("Authorization", "Bearer ")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Request body

{"name":"string","count":5,"country_code":"string"}

POST /api/v1/agent/confirm-pin

Reserve a VayaPin name and send the signup link to the user

Finalise a reservation and dispatch the signup link.

202 — name reserved, link sent: {reservation_id, expires_at}.
404 — name_not_available (cs-api says the name is taken); the body carries suggestions so the agent can re-prompt.
422 — invalid request body (name pattern / channel / callback_url), or the destination was rejected by the channel provider.
503 — channel_not_available (WhatsApp before Meta verification), or a transient cs-api / channel-provider failure (detail masked).
502 / 500 — cs-api contract mismatch / our token misconfigured.

Responses

202Successful Response
422Validation Error

POST /api/v1/agent/confirm-pin

curl -X POST 'https://api.example.com/api/v1/agent/confirm-pin' \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "country_code": "string",
  "identifier": "string",
  "channel": "sms",
  "callback_url": "https://example.com"
}'

import httpx

resp = httpx.post(
    "https://api.example.com/api/v1/agent/confirm-pin",
    headers={"Authorization": "Bearer ", "Content-Type": "application/json"},
    json={"name": "string", "country_code": "string", "identifier": "string", "channel": "sms", "callback_url": "https://example.com"},
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.example.com/api/v1/agent/confirm-pin", {
  method: "POST",
  headers: { "Authorization": "Bearer ", "Content-Type": "application/json" },
  body: JSON.stringify({"name": "string", "country_code": "string", "identifier": "string", "channel": "sms", "callback_url": "https://example.com"})
});
const data = await resp.json();
console.log(data);

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"name": "string", "country_code": "string", "identifier": "string", "channel": "sms", "callback_url": "https://example.com"}`)
	req, _ := http.NewRequest("POST", "https://api.example.com/api/v1/agent/confirm-pin", body)
	req.Header.Set("Authorization", "Bearer ")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Request body

{"name":"string","channel":"sms","identifier":"string","callback_url":"https://example.com","country_code":"string"}

POST /api/v1/agent/proxy/google-maps/{path}

BYOK passthrough to the Google Maps Platform

Parameters

path string path required

Google Maps sub-path, e.g. 'geocode/json'.

Responses

200Successful Response
422Validation Error

POST /api/v1/agent/proxy/google-maps/{path}

curl -X POST 'https://api.example.com/api/v1/agent/proxy/google-maps/{path}' \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {}
}'

import httpx

resp = httpx.post(
    "https://api.example.com/api/v1/agent/proxy/google-maps/{path}",
    headers={"Authorization": "Bearer ", "Content-Type": "application/json"},
    json={"params": {}},
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.example.com/api/v1/agent/proxy/google-maps/{path}", {
  method: "POST",
  headers: { "Authorization": "Bearer ", "Content-Type": "application/json" },
  body: JSON.stringify({"params": {}})
});
const data = await resp.json();
console.log(data);

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"params": {}}`)
	req, _ := http.NewRequest("POST", "https://api.example.com/api/v1/agent/proxy/google-maps/{path}", body)
	req.Header.Set("Authorization", "Bearer ")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Request body

{"params":{}}