Async Account Creation

The POST /accounts endpoint supports asynchronous account creation via a callback URL.

See Open API Spec

How It Works

1. You send a POST /accounts request with a callbackUrl field in the body.

2. The API validates the request and returns 202 Accepted immediately with a requestId.

3. The account is created in the background.

4. Once finished (success or failure), the result is POSTed to your callback URL.

Without callbackUrl, the endpoint behaves exactly as before - synchronous, blocking until the account is created.

---

Timeouts

Mode	Recommended Read Timeout	Why
Sync (POST /accounts without callbackUrl)	100 seconds	The synchronous endpoint completes within 100 seconds. If it takes longer, the request is likely stuck.
Async (POST /accounts with callbackUrl)	N/A	The API returns 202 Accepted instantly. The result arrives via callback - no timeout to worry about.
Polling (GET /accounts/async/{requestId})	300 seconds (if waiting)	Async account creation includes internal retries and can take up to 300 seconds. Poll periodically until the status is COMPLETED or FAILED.

Important: The async flow internally retries broker connections and waits for system capacity, which is why it can take up to 300 seconds. This is handled entirely server-side - your client just needs to wait for the callback or poll.

---

Quick Start

1. Create Account (Async)

curl -X POST https://api.metacopier.io/rest/api/v1/accounts \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": { "id": 1 },
    "region": { "id": 1 },
    "loginServer": "ICMarketsSC-MT5-4",
    "loginAccountNumber": "12345678",
    "loginAccountPassword": "your_password",
    "callbackUrl": "https://your-server.com/webhook/account-created"
  }'

Response - 202 Accepted

{
  "requestId": "acc_a1b2c3d4e5f67890",
  "message": "Account creation request accepted. The result will be POSTed to the provided callback URL.",
  "callbackUrl": "https://your-server.com/webhook/account-created",
  "status": "QUEUED"
}

---

Callback Payload

When the account creation completes, a POST request is sent to your callbackUrl.

On Success

{
  "requestId": "acc_a1b2c3d4e5f67890",
  "success": true,
  "account": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": { "id": 1, "name": "MT5" },
    "region": { "id": 1, "name": "New York" },
    "loginServer": "ICMarketsSC-MT5-4",
    "loginAccountNumber": "12345678",
    "accountInformation": {
      "connected": true
    }
  },
  "error": null
}

On Failure

{
  "requestId": "acc_a1b2c3d4e5f67890",
  "success": false,
  "account": null,
  "error": "[WRONG_CREDENTIALS]"
}

Callback Headers

Header	Description
Content-Type	application/json
X-Request-Id	The requestId for correlation

Retry Policy

If your callback endpoint is unavailable, the request is retried:

• 3 attempts total

• Backoff: 2 seconds after attempt 1, 4 seconds after attempt 2

• Each retry uses a different IP address (rotating proxy)

---

Polling (Optional)

You can also poll for status instead of (or in addition to) using callbacks.

Get Status of a Single Request

curl https://api.metacopier.io/rest/api/v1/accounts/async/acc_a1b2c3d4e5f67890 \
  -H "X-API-KEY: YOUR_API_KEY"

Response:

{
  "requestId": "acc_a1b2c3d4e5f67890",
  "status": "COMPLETED",
  "account": { ... },
  "error": null
}

Get All Async Requests

curl https://api.metacopier.io/rest/api/v1/accounts/async \
  -H "X-API-KEY: YOUR_API_KEY"

Returns an array of all tracked async requests for your project.

---

Status Lifecycle

Status	Description
QUEUED	Request accepted, waiting to be processed
PROCESSING	Account is currently being created
COMPLETED	Account created successfully (includes account field)
FAILED	Account creation failed (includes error field)

Statuses are retained for 1 hour after completion, then automatically removed.

---

Processing Rules

• Sequential per project: Only 1 account creation runs at a time per project. Additional requests are queued and processed in order.

---

Callback URL Requirements

Rule	Details
Protocol	https:// or http://
Format	Must be a valid URL
Method	Your endpoint must accept POST requests
Response	Return any 2xx status code to acknowledge receipt

If the URL is invalid, the API returns 400 Bad Request with one of:

• [CALLBACK_URL_REQUIRED] - field is present but empty

• [CALLBACK_URL_INVALID] - malformed URL

• [CALLBACK_URL_INVALID_PROTOCOL] - protocol is not http/https

---

Error Codes

All standard POST /accounts errors apply. These are returned synchronously (before the 202) if validation fails:

Error	HTTP Status	Description
[CALLBACK_URL_INVALID]	400	Malformed callback URL
[CALLBACK_URL_INVALID_PROTOCOL]	400	Callback URL must use http or https
[REGION_NOT_FOUND]	404	Invalid region ID
[ACCOUNT_TYPE_NOT_FOUND]	404	Invalid account type ID
[ACCOUNT_LEVEL_API_KEY_CANNOT_CREATE_ACCOUNTS]	403	Must use a project-level API key

Errors that occur during async processing are delivered via the callback payload and the polling endpoint (status = FAILED).

---

Example: Node.js Callback Server

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook/account-created', (req, res) => {
  const { requestId, success, account, error } = req.body;

  if (success) {
    console.log(`Account created: ${account.id} (request: ${requestId})`);
    // Store the account, update your database, etc.
  } else {
    console.error(`Account creation failed: ${error} (request: ${requestId})`);
    // Handle the error, notify your user, etc.
  }

  res.status(200).send('OK');
});

app.listen(3000);