curl --request POST \
--url https://api.paygentic.io/v0/externalReferences \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"merchantId": "<string>",
"entityId": "<string>",
"provider": "<string>",
"externalId": "<string>",
"externalLabel": "<string>",
"metadata": {},
"isPrimary": true,
"isDefault": true,
"moveClaim": true
}
'import requests
url = "https://api.paygentic.io/v0/externalReferences"
payload = {
"merchantId": "<string>",
"entityId": "<string>",
"provider": "<string>",
"externalId": "<string>",
"externalLabel": "<string>",
"metadata": {},
"isPrimary": True,
"isDefault": True,
"moveClaim": True
}
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({
merchantId: '<string>',
entityId: '<string>',
provider: '<string>',
externalId: '<string>',
externalLabel: '<string>',
metadata: {},
isPrimary: true,
isDefault: true,
moveClaim: true
})
};
fetch('https://api.paygentic.io/v0/externalReferences', 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://api.paygentic.io/v0/externalReferences",
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([
'merchantId' => '<string>',
'entityId' => '<string>',
'provider' => '<string>',
'externalId' => '<string>',
'externalLabel' => '<string>',
'metadata' => [
],
'isPrimary' => true,
'isDefault' => true,
'moveClaim' => true
]),
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://api.paygentic.io/v0/externalReferences"
payload := strings.NewReader("{\n \"merchantId\": \"<string>\",\n \"entityId\": \"<string>\",\n \"provider\": \"<string>\",\n \"externalId\": \"<string>\",\n \"externalLabel\": \"<string>\",\n \"metadata\": {},\n \"isPrimary\": true,\n \"isDefault\": true,\n \"moveClaim\": true\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://api.paygentic.io/v0/externalReferences")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"merchantId\": \"<string>\",\n \"entityId\": \"<string>\",\n \"provider\": \"<string>\",\n \"externalId\": \"<string>\",\n \"externalLabel\": \"<string>\",\n \"metadata\": {},\n \"isPrimary\": true,\n \"isDefault\": true,\n \"moveClaim\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.paygentic.io/v0/externalReferences")
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 \"merchantId\": \"<string>\",\n \"entityId\": \"<string>\",\n \"provider\": \"<string>\",\n \"externalId\": \"<string>\",\n \"externalLabel\": \"<string>\",\n \"metadata\": {},\n \"isPrimary\": true,\n \"isDefault\": true,\n \"moveClaim\": true\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"object": "externalReference",
"merchantId": "<string>",
"entityType": "item",
"entityId": "<string>",
"provider": "<string>",
"externalId": "<string>",
"metadata": {},
"isPrimary": true,
"isDefault": true,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"externalLabel": "<string>"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}Create
curl --request POST \
--url https://api.paygentic.io/v0/externalReferences \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"merchantId": "<string>",
"entityId": "<string>",
"provider": "<string>",
"externalId": "<string>",
"externalLabel": "<string>",
"metadata": {},
"isPrimary": true,
"isDefault": true,
"moveClaim": true
}
'import requests
url = "https://api.paygentic.io/v0/externalReferences"
payload = {
"merchantId": "<string>",
"entityId": "<string>",
"provider": "<string>",
"externalId": "<string>",
"externalLabel": "<string>",
"metadata": {},
"isPrimary": True,
"isDefault": True,
"moveClaim": True
}
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({
merchantId: '<string>',
entityId: '<string>',
provider: '<string>',
externalId: '<string>',
externalLabel: '<string>',
metadata: {},
isPrimary: true,
isDefault: true,
moveClaim: true
})
};
fetch('https://api.paygentic.io/v0/externalReferences', 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://api.paygentic.io/v0/externalReferences",
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([
'merchantId' => '<string>',
'entityId' => '<string>',
'provider' => '<string>',
'externalId' => '<string>',
'externalLabel' => '<string>',
'metadata' => [
],
'isPrimary' => true,
'isDefault' => true,
'moveClaim' => true
]),
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://api.paygentic.io/v0/externalReferences"
payload := strings.NewReader("{\n \"merchantId\": \"<string>\",\n \"entityId\": \"<string>\",\n \"provider\": \"<string>\",\n \"externalId\": \"<string>\",\n \"externalLabel\": \"<string>\",\n \"metadata\": {},\n \"isPrimary\": true,\n \"isDefault\": true,\n \"moveClaim\": true\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://api.paygentic.io/v0/externalReferences")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"merchantId\": \"<string>\",\n \"entityId\": \"<string>\",\n \"provider\": \"<string>\",\n \"externalId\": \"<string>\",\n \"externalLabel\": \"<string>\",\n \"metadata\": {},\n \"isPrimary\": true,\n \"isDefault\": true,\n \"moveClaim\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.paygentic.io/v0/externalReferences")
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 \"merchantId\": \"<string>\",\n \"entityId\": \"<string>\",\n \"provider\": \"<string>\",\n \"externalId\": \"<string>\",\n \"externalLabel\": \"<string>\",\n \"metadata\": {},\n \"isPrimary\": true,\n \"isDefault\": true,\n \"moveClaim\": true\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"object": "externalReference",
"merchantId": "<string>",
"entityType": "item",
"entityId": "<string>",
"provider": "<string>",
"externalId": "<string>",
"metadata": {},
"isPrimary": true,
"isDefault": true,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"externalLabel": "<string>"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}Authorizations
API key authentication
Body
^org_[a-zA-Z0-9]+$The type of Paygentic entity this external reference points at
item, customer Paygentic id of the entity, e.g. itm_xxx
Lowercase snake_case provider identifier (e.g. salesforce, netsuite)
64^[a-z][a-z0-9_]*$Identifier of the record in the external system
255^[a-zA-Z0-9_-]+$Human-friendly name shown in UIs (e.g. a NetSuite financial-treatment name)
255Provider-specific fields (e.g. { "sfObject": "Product2" })
Whether this reference claims (provider, externalId) — the code resolves back to this one entity. Unique per merchant; unclaimed references are aliases. Omitting it claims the code. Send false for a code that is only ever sent outward, such as a ledger account several items post to — claiming that refuses the second item to use it. The default is not derived from the provider: what a code is for is a property of the operation recording it, and one provider can both resolve an arriving code and be sent a selected one. Declaring a schema default here would defeat the distinction, because a generated client materialises the default into the request body and the caller can no longer express "I did not say".
Whether this is the code sent to the provider for this entity. At most one per (entityType, entityId, provider). Omit to have the entity's first code for the provider designated automatically — see the note on isPrimary for why this carries no schema default.
Take this code's claim from whichever entity currently holds it, in the same transaction.
Without it, claiming a code another entity claims is a 409 identifying the holder — the right answer to an accident, and the common case. With it, the reassignment is the point.
It exists because the alternative route — remove the old claim, then create the new one — leaves a window in which the code resolves to nothing. An arrival in that window is still recorded, untagged rather than rejected, so nothing is lost; but it is silent while it lasts and leaves work to repair.
Deliberately opt-in, unlike moving a designation. A designation moves within one entity; a claim moves between entities and changes what future arrivals resolve to, which should never be a side effect of recording a code. Ignored when the write is not claiming the code.
Response
External reference created
Links a Paygentic entity to a record in an external system such as Salesforce or NetSuite.
Unique identifier for an external reference
^xrf_[a-zA-Z0-9]+$externalReference Unique identifier for an organization
^org_[a-zA-Z0-9]+$The type of Paygentic entity this external reference points at
item, customer Lowercase snake_case provider identifier (e.g. salesforce, netsuite)
64^[a-z][a-z0-9_]*$Optional external identifier for cross-referencing with external systems. Alphanumeric characters, hyphens, and underscores only.
255^[a-zA-Z0-9_-]+$Was this page helpful?