Bulk-create unlinked accounts with import keys
Create up to 100 unlinked accounts in one call — for giveaways, competitions, or pre-provisioning inventory.
Every account is created with:
- no trader attached (
userId: null) - its own one-time
importKey(serial-key style, e.g.HP-7K3QF-9XT2M-4WHRD) not_startedstatus- no billing and no CME entitlement — both start only when a key is redeemed
Hand each importKey to a customer; they redeem it inside the Hyperprop app under Trading Accounts → Import. Each redemption fires an account.imported webhook with the redeemer’s email, the key, and a timestamp — your verification trail.
customerIdPrefix is required: each account gets a sequential customerId (promo-summer-001, promo-summer-002, …) you can query later via GET /trading-accounts?customerId=.... Numbering continues after the highest number the prefix already has in your organization, so a second call with the same prefix starts at -101 after a first call of 100.
Soulbound note: identity bindings are keyed on customerId, and sequential prefix ids give every account a different placeholder customer — right for giveaways where each key goes to a different winner (each redemption creates its own binding). If several accounts in a batch are for the SAME customer, PATCH their customerId to that customer’s real ID after creation so all their imports enforce one shared Hyperprop login.
List remaining unredeemed accounts (keys included) anytime with GET /trading-accounts?unlinked=true.
An account.created webhook fires for each account with data.importKey, data.metadata.unlinked: true, and a shared batch_id.
Permissions: organization admins only.
Error codes: VALIDATION_ERROR, PLAN_NOT_FOUND, PLAN_NOT_ACTIVE, NO_TRADING_RULE, RULE_NOT_FOUND, BULK_CREATE_ERROR.
Access: full-access API keys only (a read-only key gets 403 READ_ONLY_KEY). Dashboard members need manage access to Traders & accounts.
curl --request POST \
--url https://api.hyperprop.com/platform/v1/organization/trading-accounts/bulk \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"count": 25,
"type": "evaluation",
"tradingPlanId": "550e8400-e29b-41d4-a716-446655440000",
"tradingRuleId": "<string>",
"initialBalance": 50000,
"customerIdPrefix": "promo-summer",
"externalRefPrefix": "promo-summer",
"metadata": {
"campaign": "summer-giveaway"
}
}
'import requests
url = "https://api.hyperprop.com/platform/v1/organization/trading-accounts/bulk"
payload = {
"count": 25,
"type": "evaluation",
"tradingPlanId": "550e8400-e29b-41d4-a716-446655440000",
"tradingRuleId": "<string>",
"initialBalance": 50000,
"customerIdPrefix": "promo-summer",
"externalRefPrefix": "promo-summer",
"metadata": { "campaign": "summer-giveaway" }
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
count: 25,
type: 'evaluation',
tradingPlanId: '550e8400-e29b-41d4-a716-446655440000',
tradingRuleId: '<string>',
initialBalance: 50000,
customerIdPrefix: 'promo-summer',
externalRefPrefix: 'promo-summer',
metadata: {campaign: 'summer-giveaway'}
})
};
fetch('https://api.hyperprop.com/platform/v1/organization/trading-accounts/bulk', 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.hyperprop.com/platform/v1/organization/trading-accounts/bulk",
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([
'count' => 25,
'type' => 'evaluation',
'tradingPlanId' => '550e8400-e29b-41d4-a716-446655440000',
'tradingRuleId' => '<string>',
'initialBalance' => 50000,
'customerIdPrefix' => 'promo-summer',
'externalRefPrefix' => 'promo-summer',
'metadata' => [
'campaign' => 'summer-giveaway'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$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.hyperprop.com/platform/v1/organization/trading-accounts/bulk"
payload := strings.NewReader("{\n \"count\": 25,\n \"type\": \"evaluation\",\n \"tradingPlanId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"tradingRuleId\": \"<string>\",\n \"initialBalance\": 50000,\n \"customerIdPrefix\": \"promo-summer\",\n \"externalRefPrefix\": \"promo-summer\",\n \"metadata\": {\n \"campaign\": \"summer-giveaway\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
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.hyperprop.com/platform/v1/organization/trading-accounts/bulk")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"count\": 25,\n \"type\": \"evaluation\",\n \"tradingPlanId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"tradingRuleId\": \"<string>\",\n \"initialBalance\": 50000,\n \"customerIdPrefix\": \"promo-summer\",\n \"externalRefPrefix\": \"promo-summer\",\n \"metadata\": {\n \"campaign\": \"summer-giveaway\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hyperprop.com/platform/v1/organization/trading-accounts/bulk")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"count\": 25,\n \"type\": \"evaluation\",\n \"tradingPlanId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"tradingRuleId\": \"<string>\",\n \"initialBalance\": 50000,\n \"customerIdPrefix\": \"promo-summer\",\n \"externalRefPrefix\": \"promo-summer\",\n \"metadata\": {\n \"campaign\": \"summer-giveaway\"\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "25 unlinked account(s) created — hand each importKey to its trader",
"data": {
"batchId": "<string>",
"created": 25,
"tradingPlan": {
"id": "<string>",
"name": "<string>"
},
"tradingRule": {
"id": "<string>",
"name": "<string>"
},
"accounts": [
{
"id": "<string>",
"accountNumber": "<string>",
"customerId": "promo-summer-001",
"externalRef": "<string>",
"importKey": "HP-7K3QF-9XT2M-4WHRD"
}
]
}
}{
"success": false,
"statusCode": 400,
"error": "Bad Request",
"message": "Validation failed (`VALIDATION_ERROR`), or metadata over the size limits (`METADATA_TOO_LARGE`)",
"code": "VALIDATION_ERROR"
}{
"success": false,
"statusCode": 401,
"error": "Unauthorized",
"message": "Authentication required",
"code": "UNAUTHORIZED"
}{
"success": false,
"statusCode": 403,
"error": "Forbidden",
"message": "Only organization admins can perform this action",
"code": "NOT_ADMIN"
}{
"success": false,
"statusCode": 404,
"error": "Not Found",
"message": "Trading plan not found",
"code": "PLAN_NOT_FOUND"
}{
"success": false,
"statusCode": 409,
"error": "Conflict",
"message": "These accounts would take your organization past its limit of 25,000 unassigned accounts; the message says how many fit",
"code": "UNCLAIMED_ACCOUNT_LIMIT"
}{
"success": false,
"statusCode": 429,
"error": "Too Many Requests",
"message": "Too many requests to this endpoint. Try again in 12 second(s).",
"code": "RATE_LIMITED"
}{
"success": false,
"statusCode": 500,
"error": "Internal Server Error",
"message": "An unexpected error occurred",
"code": "INTERNAL_ERROR"
}{
"success": false,
"statusCode": 503,
"error": "Service Unavailable",
"message": "The Idempotency-Key could not be recorded, so the request was not run. Retry with the same key.",
"code": "IDEMPOTENCY_UNAVAILABLE"
}Authorizations
Organization API key (hp_live_...), sent in the X-API-Key header. Create, rotate and restrict keys in the dashboard or with the API keys endpoints; an organization can have two active keys, so you can rotate without downtime. A full-access key can call every endpoint in this reference. A read-only key can call GET endpoints (and create a trading stream token); any other request returns 403 READ_ONLY_KEY. A key with an IP allowlist returns 403 IP_NOT_ALLOWED from any other address. Each endpoint lists which keys can call it under Access.
Headers
Optional. A value that identifies this operation on your side, at most 255 characters. A retry with the same key, method, path and body within 24 hours returns the original response (with Idempotency-Replayed: true) instead of repeating the change. The same key with a different body returns 409 IDEMPOTENCY_KEY_REUSED; a retry while the first request is still running returns 409 IDEMPOTENCY_KEY_IN_PROGRESS. A response that contains a credential (such as a new API key or signing secret) is not saved: the change is still not repeated, and a retry returns 409 IDEMPOTENCY_KEY_COMPLETED with the original status in originalStatus. Server errors (5xx) are not saved, so a retry runs again. If the key cannot be recorded, the request is not run and returns 503 IDEMPOTENCY_UNAVAILABLE; retry with the same key.
255Body
REQUIRED. Each account gets customerId {prefix}-001, {prefix}-002, ... — one placeholder customer per account (right for giveaways where every key goes to a different winner). PATCH the real customerId onto an account once you know who it belongs to.
200"promo-summer"
curl --request POST \
--url https://api.hyperprop.com/platform/v1/organization/trading-accounts/bulk \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"count": 25,
"type": "evaluation",
"tradingPlanId": "550e8400-e29b-41d4-a716-446655440000",
"tradingRuleId": "<string>",
"initialBalance": 50000,
"customerIdPrefix": "promo-summer",
"externalRefPrefix": "promo-summer",
"metadata": {
"campaign": "summer-giveaway"
}
}
'import requests
url = "https://api.hyperprop.com/platform/v1/organization/trading-accounts/bulk"
payload = {
"count": 25,
"type": "evaluation",
"tradingPlanId": "550e8400-e29b-41d4-a716-446655440000",
"tradingRuleId": "<string>",
"initialBalance": 50000,
"customerIdPrefix": "promo-summer",
"externalRefPrefix": "promo-summer",
"metadata": { "campaign": "summer-giveaway" }
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
count: 25,
type: 'evaluation',
tradingPlanId: '550e8400-e29b-41d4-a716-446655440000',
tradingRuleId: '<string>',
initialBalance: 50000,
customerIdPrefix: 'promo-summer',
externalRefPrefix: 'promo-summer',
metadata: {campaign: 'summer-giveaway'}
})
};
fetch('https://api.hyperprop.com/platform/v1/organization/trading-accounts/bulk', 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.hyperprop.com/platform/v1/organization/trading-accounts/bulk",
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([
'count' => 25,
'type' => 'evaluation',
'tradingPlanId' => '550e8400-e29b-41d4-a716-446655440000',
'tradingRuleId' => '<string>',
'initialBalance' => 50000,
'customerIdPrefix' => 'promo-summer',
'externalRefPrefix' => 'promo-summer',
'metadata' => [
'campaign' => 'summer-giveaway'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$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.hyperprop.com/platform/v1/organization/trading-accounts/bulk"
payload := strings.NewReader("{\n \"count\": 25,\n \"type\": \"evaluation\",\n \"tradingPlanId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"tradingRuleId\": \"<string>\",\n \"initialBalance\": 50000,\n \"customerIdPrefix\": \"promo-summer\",\n \"externalRefPrefix\": \"promo-summer\",\n \"metadata\": {\n \"campaign\": \"summer-giveaway\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
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.hyperprop.com/platform/v1/organization/trading-accounts/bulk")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"count\": 25,\n \"type\": \"evaluation\",\n \"tradingPlanId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"tradingRuleId\": \"<string>\",\n \"initialBalance\": 50000,\n \"customerIdPrefix\": \"promo-summer\",\n \"externalRefPrefix\": \"promo-summer\",\n \"metadata\": {\n \"campaign\": \"summer-giveaway\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hyperprop.com/platform/v1/organization/trading-accounts/bulk")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"count\": 25,\n \"type\": \"evaluation\",\n \"tradingPlanId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"tradingRuleId\": \"<string>\",\n \"initialBalance\": 50000,\n \"customerIdPrefix\": \"promo-summer\",\n \"externalRefPrefix\": \"promo-summer\",\n \"metadata\": {\n \"campaign\": \"summer-giveaway\"\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "25 unlinked account(s) created — hand each importKey to its trader",
"data": {
"batchId": "<string>",
"created": 25,
"tradingPlan": {
"id": "<string>",
"name": "<string>"
},
"tradingRule": {
"id": "<string>",
"name": "<string>"
},
"accounts": [
{
"id": "<string>",
"accountNumber": "<string>",
"customerId": "promo-summer-001",
"externalRef": "<string>",
"importKey": "HP-7K3QF-9XT2M-4WHRD"
}
]
}
}{
"success": false,
"statusCode": 400,
"error": "Bad Request",
"message": "Validation failed (`VALIDATION_ERROR`), or metadata over the size limits (`METADATA_TOO_LARGE`)",
"code": "VALIDATION_ERROR"
}{
"success": false,
"statusCode": 401,
"error": "Unauthorized",
"message": "Authentication required",
"code": "UNAUTHORIZED"
}{
"success": false,
"statusCode": 403,
"error": "Forbidden",
"message": "Only organization admins can perform this action",
"code": "NOT_ADMIN"
}{
"success": false,
"statusCode": 404,
"error": "Not Found",
"message": "Trading plan not found",
"code": "PLAN_NOT_FOUND"
}{
"success": false,
"statusCode": 409,
"error": "Conflict",
"message": "These accounts would take your organization past its limit of 25,000 unassigned accounts; the message says how many fit",
"code": "UNCLAIMED_ACCOUNT_LIMIT"
}{
"success": false,
"statusCode": 429,
"error": "Too Many Requests",
"message": "Too many requests to this endpoint. Try again in 12 second(s).",
"code": "RATE_LIMITED"
}{
"success": false,
"statusCode": 500,
"error": "Internal Server Error",
"message": "An unexpected error occurred",
"code": "INTERNAL_ERROR"
}{
"success": false,
"statusCode": 503,
"error": "Service Unavailable",
"message": "The Idempotency-Key could not be recorded, so the request was not run. Retry with the same key.",
"code": "IDEMPOTENCY_UNAVAILABLE"
}