Account

Embed
Preview of the card
<a href="https://numestri.com/docs/ref-account"><img src="https://numestri.com/docs/_api/public/orgs/25229885-9620-4c08-bd2e-a0d0d74ac8b6/spaces/ef21e0c3-966d-4b03-b6d2-e66d449835d4/pages/3a0cc362-4243-4bdb-bfe5-926c570cde53/social-card.svg?v=3e7ae33eec8b" alt="Account" width="600" height="315"></a>
GEThttps://numestri.com/api/v1/request/balance
Get your balance

Your current balance in US dollars, as a fixed two-decimal string.

Also accepts POST, with the same parameters in a form (application/x-www-form-urlencoded) or JSON body.

Code samples
cURL
curl -X GET "https://numestri.com/api/v1/request/balance"
TypeScript
const res = await fetch('https://numestri.com/api/v1/request/balance', {
  method: 'GET',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "GET",
    "https://numestri.com/api/v1/request/balance",
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://numestri.com/api/v1/request/balance", nil)
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}
PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://numestri.com/api/v1/request/balance');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Ruby
require 'net/http'
require 'uri'

uri = URI('https://numestri.com/api/v1/request/balance')
req = Net::HTTP::Get.new(uri)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body
Java
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://numestri.com/api/v1/request/balance"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 Your balance.
Example
{
  "balance": "48.06"
}
Schema
balancestringrequired
US dollars, as a fixed two-decimal string.
400 A parameter (or the API key) is missing or invalid. param names it.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
403 The API key is not valid.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
429 Over the rate limit (32 requests per second per account by default). Wait Retry-After seconds.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
500 Something went wrong on our side.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
GEThttps://numestri.com/api/v1/account/partner-code
List your partner codes

The partner codes your account holds, and what each prices for you now. A partner code gives your account its prices for as long as the code is active; where your account already has a lower price, that one stays.

Code samples
cURL
curl -X GET "https://numestri.com/api/v1/account/partner-code"
TypeScript
const res = await fetch('https://numestri.com/api/v1/account/partner-code', {
  method: 'GET',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "GET",
    "https://numestri.com/api/v1/account/partner-code",
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://numestri.com/api/v1/account/partner-code", nil)
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}
PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://numestri.com/api/v1/account/partner-code');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Ruby
require 'net/http'
require 'uri'

uri = URI('https://numestri.com/api/v1/account/partner-code')
req = Net::HTTP::Get.new(uri)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body
Java
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://numestri.com/api/v1/account/partner-code"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 Your partner codes.
Example
{
  "success": {},
  "codes": [
    {
      "code": "ticketbot123",
      "partner": "TicketBot",
      "active": true,
      "redeemed_at": "2024-01-01T00:00:00Z",
      "ends_at": "2024-01-01T00:00:00Z",
      "unlocks": [
        {
          "platform": null,
          "platform_name": null,
          "country": null,
          "product": null,
          "price": null,
          "price_without_code": null,
          "cheaper": null
        }
      ]
    }
  ]
}
Schema
successrequired
codesobject[]required
Show child parameters
codestringrequired
partnerstringrequired
activebooleanrequired
Its prices are in force (switched on, inside its dates). An inactive code lists no unlocks.
redeemed_atstringrequired
ends_atstringrequired
unlocksPartnerCodeUnlock[]required
Show child parameters
platformstringrequired
Platform id, as service takes it.
platform_namestringrequired
countrystringrequired
ISO country code, or null for every country.
productstringrequired
Null for every product.
sms | rental | email
pricestringrequired
Your price now in US dollars (null when nothing in scope is in stock).
price_without_codestringrequired
What you would pay without this code.
cheaperbooleanrequired
False when your account already had this price or better: the lower price always wins.
400 A parameter (or the API key) is missing or invalid. param names it.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
403 The API key is not valid.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
429 Over the rate limit (32 requests per second per account by default). Wait Retry-After seconds.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
500 Something went wrong on our side.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
POSThttps://numestri.com/api/v1/account/partner-code
Redeem a partner code

Redeem a partner code for your account. Codes are case-insensitive. The code's prices then apply to every price you see and pay — the catalogue, quotes and purchases — for as long as the code is active, and the lower of the code's price and your own always wins.

Redeeming a code you already hold succeeds with already_redeemed: true. Every invalid, inactive, expired or fully-used code is the same 400; repeated failures are rate-limited (429).

Request body application/x-www-form-urlencoded
codestringrequired
The partner code.
keystring
Your API key, if you send it in the body rather than a header or the query string.
{
  "code": "TICKETBOT123",
  "key": "string"
}
Code samples
cURL
curl -X POST "https://numestri.com/api/v1/account/partner-code" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d '{"code":"TICKETBOT123","key":"string"}'
TypeScript
const res = await fetch('https://numestri.com/api/v1/account/partner-code', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: JSON.stringify({"code":"TICKETBOT123","key":"string"}),
});
const data = await res.json();
Python
import requests

res = requests.request(
    "POST",
    "https://numestri.com/api/v1/account/partner-code",
    headers={
    "Content-Type": "application/x-www-form-urlencoded",
    },
    json={"code": "TICKETBOT123", "key": "string"},
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://numestri.com/api/v1/account/partner-code", strings.NewReader(`{"code":"TICKETBOT123","key":"string"}`))
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}
PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://numestri.com/api/v1/account/partner-code');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"code":"TICKETBOT123","key":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Ruby
require 'net/http'
require 'uri'

uri = URI('https://numestri.com/api/v1/account/partner-code')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/x-www-form-urlencoded'
req.body = '{"code":"TICKETBOT123","key":"string"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body
Java
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://numestri.com/api/v1/account/partner-code"))
    .header("Content-Type", "application/x-www-form-urlencoded")
    .method("POST", BodyPublishers.ofString("{\"code\":\"TICKETBOT123\",\"key\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 Redeemed (or already held): what it prices for you now.
Example
{
  "success": {},
  "code": "ticketbot123",
  "partner": "TicketBot",
  "already_redeemed": true,
  "unlocks": [
    {
      "platform": "ticketmaster",
      "platform_name": "Ticketmaster",
      "country": null,
      "product": "sms",
      "price": "0.80",
      "price_without_code": "1.20",
      "cheaper": true
    }
  ]
}
Schema
successrequired
codestringrequired
The code, lower case (codes are case-insensitive).
partnerstringrequired
already_redeemedbooleanrequired
This account already held the code; nothing changed.
unlocksPartnerCodeUnlock[]required
Show child parameters
platformstringrequired
Platform id, as service takes it.
platform_namestringrequired
countrystringrequired
ISO country code, or null for every country.
productstringrequired
Null for every product.
sms | rental | email
pricestringrequired
Your price now in US dollars (null when nothing in scope is in stock).
price_without_codestringrequired
What you would pay without this code.
cheaperbooleanrequired
False when your account already had this price or better: the lower price always wins.
400 Missing code, or not a valid partner code (param: code).
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
403 The API key is not valid.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
429 Too many failed partner code attempts, or over the rate limit. Wait Retry-After seconds.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
500 Something went wrong on our side.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
Updated