{ "openapi": "3.1.0", "info": { "title": "broker-api-wrapper", "version": "0.1.0", "description": "# Overview\nThe Broker API Wrapper provides B2B partners with a streamlined integration to our underlying brokerage infrastructure. It handles identity verification (KYC), account opening, funding, and order execution through a unified REST API.\n\n# Environments\nWe offer two environments:\n- **Sandbox**: Safely build and test your integration using mock data and simulated broker execution.\n- **Production**: Live trading environment connected to real market data and settlement networks.\n\nAccess to environments is granted as you progress through the partner onboarding process.\n\n# Authentication\nSkyBlue provisions partner API credentials securely during the integration process. \nEvery authenticated request must include your partner API key in the header:\n`Authorization: Bearer `\n\n**Security Notice:** Store your credentials securely in your backend systems. Never expose your API keys in client-side applications or public repositories.\n\n# Idempotency\nTo prevent duplicate side-effects during network failures, selected write endpoints support idempotency. Clients should generate a unique `Idempotency-Key` UUID per logical write operation.\n\nIf a request fails due to a network error, you can safely retry it with the same key. If the original request succeeded, the API will return the cached response with the `Idempotency-Replayed: true` header.\n\nIdempotency is currently supported on specific POST endpoints, such as creating persons, submitting onboarding, opening accounts, creating cash movements, and placing orders.\n\n# Errors\nThe API uses standard HTTP status codes to indicate the outcome of a request:\n- **2xx**: Success\n- **400**: Validation error or missing parameters\n- **401**: Missing or invalid partner API key\n- **403**: Forbidden (e.g., accessing resources belonging to another partner)\n- **404**: Resource not found\n- **409**: Conflict (e.g., person already exists)\n- **422**: Unprocessable Entity (business rule violation)\n- **502**: Upstream broker failure\n\n# Quickstart\nIntegrating with the Broker API Wrapper typically follows this happy-path flow:\n1. **Request API credentials** from SkyBlue.\n2. **Register a person** using `POST /v1/persons`.\n3. **Complete onboarding data** using `PATCH /v1/persons/{personId}`.\n4. Optionally **stage KYC documents** using `POST /v1/persons/{personId}/kyc/documents`.\n5. **Submit onboarding** using `POST /v1/persons/{personId}/submit`.\n6. **Upload staged KYC documents** (if applicable) using `POST /v1/persons/{personId}/kyc/documents/upload`.\n7. **Poll person status** (`GET /v1/persons/{personId}`) until the person is approved.\n8. **Open an account** using `POST /v1/persons/{personId}/accounts`.\n9. **Link a funding source** using `POST /v1/accounts/{accountId}/funding-sources`.\n10. **Create a deposit** using `POST /v1/accounts/{accountId}/deposits`.\n11. **Search instruments** using `GET /v1/instruments`.\n12. **Place an order** using `POST /v1/accounts/{accountId}/orders`.\n\n# Versioning\nThe API is currently in version 1 (`/v1`). Any backwards-incompatible changes will be introduced under a new major version path." }, "servers": [ { "url": "https://sandbox-broker.skyblueanalytics.com", "description": "Sandbox (Testing)" }, { "url": "https://api.example.com", "description": "Production (Live)" } ], "tags": [ { "name": "Person", "description": "Manage user identity, onboarding, and KYC profiles." }, { "name": "KYC Documents", "description": "Upload and submit required verification documents." }, { "name": "Accounts", "description": "Create and manage brokerage accounts." }, { "name": "Funding", "description": "Manage bank funding sources and cash movements." }, { "name": "Trading", "description": "Place and manage orders." }, { "name": "Market Data", "description": "Access real-time quotes and instrument search." }, { "name": "Health", "description": "Operational probes for system health monitoring." } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Partner API key (sk_live_...)" } }, "schemas": { "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "uptimeSeconds": { "type": "integer", "minimum": 0 }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "status", "uptimeSeconds", "timestamp" ], "example": { "status": "ok", "uptimeSeconds": 3600, "timestamp": "2023-10-27T14:30:00.000Z" } }, "ReadinessResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "notReady" ] }, "isReady": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" }, "checks": { "type": "object", "properties": { "dataSourceInitialized": { "type": "boolean" }, "databaseReachable": { "type": "boolean" } }, "required": [ "dataSourceInitialized", "databaseReachable" ] } }, "required": [ "status", "isReady", "timestamp", "checks" ], "example": { "status": "ok", "isReady": true, "timestamp": "2023-10-27T14:30:00.000Z", "checks": { "dataSourceInitialized": true, "databaseReachable": true } } }, "ApiError": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "ValidationError": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "array", "items": {} } }, "required": [ "error" ] }, "UnauthorizedError": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] }, "ForbiddenError": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] }, "RegisterPersonRequest": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1 }, "lastName": { "type": "string", "minLength": 1 }, "country": { "type": "string", "pattern": "^[A-Z]{3}$" }, "phone": { "type": "string", "minLength": 1 }, "emailAddress": { "type": "string", "format": "email" }, "language": { "type": "string", "enum": [ "en_US", "zh_CN", "es_ES", "pt_BR" ] }, "userType": { "type": "string", "enum": [ "individualTrader", "custodial" ] }, "personalInfo": { "type": "object", "properties": { "birthDay": { "type": "integer", "minimum": 1, "maximum": 31 }, "birthMonth": { "type": "integer", "minimum": 1, "maximum": 12 }, "birthYear": { "type": "integer", "minimum": 1900 }, "citizenship": { "type": "string", "pattern": "^[A-Z]{3}$" }, "politicallyExposedNames": { "type": "string" }, "irsBackupWithholdings": { "type": "boolean" }, "gender": { "type": "string", "enum": [ "male", "female" ] }, "maritalStatus": { "type": "string", "enum": [ "single", "divorced", "married", "widowed", "partner" ] } }, "required": [ "birthDay", "birthMonth", "birthYear", "citizenship" ] }, "address": { "type": "object", "properties": { "street1": { "type": "string", "minLength": 1 }, "street2": { "type": "string" }, "city": { "type": "string", "minLength": 1 }, "province": { "type": "string", "minLength": 1 }, "postalCode": { "type": "string", "minLength": 1 }, "country": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "street1", "city", "province", "postalCode", "country" ] }, "employment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "employed", "selfEmployed", "unemployed", "retired", "student" ] }, "employerName": { "type": "string" }, "occupation": { "type": "string", "enum": [ "ACCOUNTANT", "ACTUARY", "ADJUSTER", "ADMINISTRATOR", "ADVERTISER", "AGENT", "ATC", "AMBASSADOR", "ANALYST", "APPRAISER", "ARCHITECT", "ARTIST", "ASSISTANT", "ATHLETE", "ATTENDANT", "ATTORNEY", "AUCTIONEER", "AUDITOR", "BARBER", "BROKER", "BUSINESS_EXEC", "BUSINESS_OWNER", "CAREGIVER", "CARPENTER", "CASHIER", "CHEF", "CHIROPRACTOR", "CIVIL", "CLERGY", "CLERK", "COMPLIANCE", "CONSULTANT", "CONTRACTOR", "COUNSELOR", "CUSTOMER_SERVICE", "DEALER", "DEVELOPER", "DISTRIBUTOR", "DOCTOR", "DRIVER", "ENGINEER", "EXAMINER", "EXTERMINATOR", "FACTORY", "FARMER", "FINANCIAL", "FISHERMAN", "FLIGHT", "HR", "IMPEX", "INSPECTOR", "INTERN", "INVESTMENT", "INVESTOR", "IT", "JANITOR", "JEWELER", "LABORER", "LANDSCAPER", "LENDING", "MANAGER", "MECHANIC", "MILITARY", "MORTICIAN", "NURSE", "NUTRITIONIST", "OFFICE", "PHARMACIST", "PHYSICAL", "PILOT", "POLICE", "POLITICIAN", "PM", "REP", "RESEARCHER", "SAILOR", "SALES", "SCIENTIST", "SEAMSTRESS", "SECURITY", "SOCIAL", "TEACHER", "TECHNICIAN", "TELLER", "TRADESPERSON", "TRAINER", "TRANSPORTER", "UNDERWRITER", "WRITER" ] }, "companyId": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "type": { "type": "string", "enum": [ "agriculture", "mining", "utilities", "construction", "manufacturing", "wholesale", "retail", "transport", "information", "finance", "realEstate", "professional", "management", "education", "health", "art", "food", "publicSector", "waste" ] }, "broker": { "type": "boolean" }, "directorOf": { "type": "string" } }, "required": [ "status", "broker", "directorOf" ] }, "identification": { "type": "object", "properties": { "taxIdType": { "type": "string", "enum": [ "ssn", "itin", "fein", "nino", "other" ] }, "taxId": { "type": "string", "minLength": 1 }, "issuingCountry": { "type": "string", "pattern": "^[A-Z]{3}$" }, "usTaxPayer": { "type": "boolean" } }, "required": [ "taxIdType", "taxId", "issuingCountry" ] }, "disclosures": { "type": "object", "properties": { "extendedHoursAgreement": { "type": "boolean" }, "termsOfUse": { "type": "boolean" }, "customerAgreement": { "type": "boolean" }, "iraAgreement": { "type": "boolean" }, "marginAgreement": { "type": "boolean" }, "cryptoAgreements": { "type": "boolean" }, "marketDataAgreement": { "type": "boolean" }, "optionsAgreement": { "type": "boolean" }, "rule14b": { "type": "boolean" }, "finderFee": { "type": "boolean" }, "privacyPolicy": { "type": "boolean" }, "dataSharing": { "type": "boolean" }, "signedBy": { "type": "string" } }, "required": [ "extendedHoursAgreement", "termsOfUse", "customerAgreement", "iraAgreement", "marginAgreement", "cryptoAgreements", "marketDataAgreement", "optionsAgreement", "rule14b", "finderFee", "privacyPolicy", "dataSharing", "signedBy" ] }, "investorProfile": { "type": "object", "properties": { "riskTolerance": { "type": "string", "enum": [ "low", "moderate", "speculation", "high" ] }, "investmentExperience": { "type": "string", "enum": [ "none", "yrs1Less", "yrs1To2", "yrs3To5", "yrs5To10", "yrs10Plus" ] }, "investmentObjectives": { "type": "string", "enum": [ "capitalPreservation", "income", "growth", "speculation" ] }, "annualIncome": { "type": "number", "minimum": 0 }, "totalNetWorth": { "type": "number", "minimum": 0 }, "liquidNetWorth": { "type": "number", "minimum": 0 }, "dependents": { "type": "integer", "minimum": 0 }, "suitabilityEquities": { "type": "string" }, "suitabilityOptions": { "type": "string" } }, "required": [ "annualIncome", "totalNetWorth" ] }, "taxInfo": { "type": "object", "properties": { "taxTreatyWithUS": { "type": "boolean" } } } }, "required": [ "firstName", "lastName", "country", "phone", "emailAddress", "language", "userType" ], "example": { "firstName": "Jane", "lastName": "Doe", "country": "USA", "phone": "+15550100123", "emailAddress": "integration.demo@client-example.com", "language": "en_US", "userType": "individualTrader", "address": { "street1": "123 Integration Way", "city": "San Francisco", "province": "CA", "postalCode": "94105", "country": "USA" } } }, "UpdatePersonRequest": { "type": "object", "properties": { "personalInfo": { "type": "object", "properties": { "birthDay": { "type": "integer", "minimum": 1, "maximum": 31 }, "birthMonth": { "type": "integer", "minimum": 1, "maximum": 12 }, "birthYear": { "type": "integer", "minimum": 1900 }, "citizenship": { "type": "string", "pattern": "^[A-Z]{3}$" }, "politicallyExposedNames": { "type": "string" }, "irsBackupWithholdings": { "type": "boolean" }, "gender": { "type": "string", "enum": [ "male", "female" ] }, "maritalStatus": { "type": "string", "enum": [ "single", "divorced", "married", "widowed", "partner" ] } }, "required": [ "birthDay", "birthMonth", "birthYear", "citizenship" ] }, "address": { "type": "object", "properties": { "street1": { "type": "string", "minLength": 1 }, "street2": { "type": "string" }, "city": { "type": "string", "minLength": 1 }, "province": { "type": "string", "minLength": 1 }, "postalCode": { "type": "string", "minLength": 1 }, "country": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "street1", "city", "province", "postalCode", "country" ] }, "employment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "employed", "selfEmployed", "unemployed", "retired", "student" ] }, "employerName": { "type": "string" }, "occupation": { "type": "string", "enum": [ "ACCOUNTANT", "ACTUARY", "ADJUSTER", "ADMINISTRATOR", "ADVERTISER", "AGENT", "ATC", "AMBASSADOR", "ANALYST", "APPRAISER", "ARCHITECT", "ARTIST", "ASSISTANT", "ATHLETE", "ATTENDANT", "ATTORNEY", "AUCTIONEER", "AUDITOR", "BARBER", "BROKER", "BUSINESS_EXEC", "BUSINESS_OWNER", "CAREGIVER", "CARPENTER", "CASHIER", "CHEF", "CHIROPRACTOR", "CIVIL", "CLERGY", "CLERK", "COMPLIANCE", "CONSULTANT", "CONTRACTOR", "COUNSELOR", "CUSTOMER_SERVICE", "DEALER", "DEVELOPER", "DISTRIBUTOR", "DOCTOR", "DRIVER", "ENGINEER", "EXAMINER", "EXTERMINATOR", "FACTORY", "FARMER", "FINANCIAL", "FISHERMAN", "FLIGHT", "HR", "IMPEX", "INSPECTOR", "INTERN", "INVESTMENT", "INVESTOR", "IT", "JANITOR", "JEWELER", "LABORER", "LANDSCAPER", "LENDING", "MANAGER", "MECHANIC", "MILITARY", "MORTICIAN", "NURSE", "NUTRITIONIST", "OFFICE", "PHARMACIST", "PHYSICAL", "PILOT", "POLICE", "POLITICIAN", "PM", "REP", "RESEARCHER", "SAILOR", "SALES", "SCIENTIST", "SEAMSTRESS", "SECURITY", "SOCIAL", "TEACHER", "TECHNICIAN", "TELLER", "TRADESPERSON", "TRAINER", "TRANSPORTER", "UNDERWRITER", "WRITER" ] }, "companyId": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "type": { "type": "string", "enum": [ "agriculture", "mining", "utilities", "construction", "manufacturing", "wholesale", "retail", "transport", "information", "finance", "realEstate", "professional", "management", "education", "health", "art", "food", "publicSector", "waste" ] }, "broker": { "type": "boolean" }, "directorOf": { "type": "string" } }, "required": [ "status", "broker", "directorOf" ] }, "identification": { "type": "object", "properties": { "taxIdType": { "type": "string", "enum": [ "ssn", "itin", "fein", "nino", "other" ] }, "taxId": { "type": "string", "minLength": 1 }, "issuingCountry": { "type": "string", "pattern": "^[A-Z]{3}$" }, "usTaxPayer": { "type": "boolean" } }, "required": [ "taxIdType", "taxId", "issuingCountry" ] }, "disclosures": { "type": "object", "properties": { "extendedHoursAgreement": { "type": "boolean" }, "termsOfUse": { "type": "boolean" }, "customerAgreement": { "type": "boolean" }, "iraAgreement": { "type": "boolean" }, "marginAgreement": { "type": "boolean" }, "cryptoAgreements": { "type": "boolean" }, "marketDataAgreement": { "type": "boolean" }, "optionsAgreement": { "type": "boolean" }, "rule14b": { "type": "boolean" }, "finderFee": { "type": "boolean" }, "privacyPolicy": { "type": "boolean" }, "dataSharing": { "type": "boolean" }, "signedBy": { "type": "string" } }, "required": [ "extendedHoursAgreement", "termsOfUse", "customerAgreement", "iraAgreement", "marginAgreement", "cryptoAgreements", "marketDataAgreement", "optionsAgreement", "rule14b", "finderFee", "privacyPolicy", "dataSharing", "signedBy" ] }, "investorProfile": { "type": "object", "properties": { "riskTolerance": { "type": "string", "enum": [ "low", "moderate", "speculation", "high" ] }, "investmentExperience": { "type": "string", "enum": [ "none", "yrs1Less", "yrs1To2", "yrs3To5", "yrs5To10", "yrs10Plus" ] }, "investmentObjectives": { "type": "string", "enum": [ "capitalPreservation", "income", "growth", "speculation" ] }, "annualIncome": { "type": "number", "minimum": 0 }, "totalNetWorth": { "type": "number", "minimum": 0 }, "liquidNetWorth": { "type": "number", "minimum": 0 }, "dependents": { "type": "integer", "minimum": 0 }, "suitabilityEquities": { "type": "string" }, "suitabilityOptions": { "type": "string" } }, "required": [ "annualIncome", "totalNetWorth" ] }, "taxInfo": { "type": "object", "properties": { "taxTreatyWithUS": { "type": "boolean" } } } }, "description": "Partial update payload for onboarding categories. Clients may send one or more complete category objects in the same request. When a category is included, all required fields for that category must be supplied together because category updates are applied with replace semantics rather than field-by-field patch semantics.", "example": { "personalInfo": { "birthDay": 15, "birthMonth": 8, "birthYear": 1985, "citizenship": "USA", "gender": "female", "maritalStatus": "single" }, "employment": { "status": "employed", "employerName": "Acme Corp", "occupation": "ENGINEER", "from": "2020", "broker": false, "directorOf": "Acme Ventures LLC" } } }, "PersonWithStatusResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "partnerId": { "type": "string" }, "emailAddress": { "type": "string", "format": "email" }, "kycStatus": { "type": "string", "enum": [ "pending", "inReview", "needsMoreInfo", "approved", "rejected", "expired" ] }, "country": { "type": "string", "pattern": "^[A-Z]{3}$" }, "language": { "type": "string" }, "personalInfo": { "type": "object", "properties": { "birthDay": { "type": "integer", "minimum": 1, "maximum": 31 }, "birthMonth": { "type": "integer", "minimum": 1, "maximum": 12 }, "birthYear": { "type": "integer", "minimum": 1900 }, "citizenship": { "type": "string", "pattern": "^[A-Z]{3}$" }, "politicallyExposedNames": { "type": "string" }, "irsBackupWithholdings": { "type": "boolean" }, "gender": { "type": "string", "enum": [ "male", "female" ] }, "maritalStatus": { "type": "string", "enum": [ "single", "divorced", "married", "widowed", "partner" ] } }, "required": [ "birthDay", "birthMonth", "birthYear", "citizenship" ] }, "address": { "type": "object", "properties": { "street1": { "type": "string", "minLength": 1 }, "street2": { "type": "string" }, "city": { "type": "string", "minLength": 1 }, "province": { "type": "string", "minLength": 1 }, "postalCode": { "type": "string", "minLength": 1 }, "country": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "street1", "city", "province", "postalCode", "country" ] }, "employment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "employed", "selfEmployed", "unemployed", "retired", "student" ] }, "employerName": { "type": "string" }, "occupation": { "type": "string", "enum": [ "ACCOUNTANT", "ACTUARY", "ADJUSTER", "ADMINISTRATOR", "ADVERTISER", "AGENT", "ATC", "AMBASSADOR", "ANALYST", "APPRAISER", "ARCHITECT", "ARTIST", "ASSISTANT", "ATHLETE", "ATTENDANT", "ATTORNEY", "AUCTIONEER", "AUDITOR", "BARBER", "BROKER", "BUSINESS_EXEC", "BUSINESS_OWNER", "CAREGIVER", "CARPENTER", "CASHIER", "CHEF", "CHIROPRACTOR", "CIVIL", "CLERGY", "CLERK", "COMPLIANCE", "CONSULTANT", "CONTRACTOR", "COUNSELOR", "CUSTOMER_SERVICE", "DEALER", "DEVELOPER", "DISTRIBUTOR", "DOCTOR", "DRIVER", "ENGINEER", "EXAMINER", "EXTERMINATOR", "FACTORY", "FARMER", "FINANCIAL", "FISHERMAN", "FLIGHT", "HR", "IMPEX", "INSPECTOR", "INTERN", "INVESTMENT", "INVESTOR", "IT", "JANITOR", "JEWELER", "LABORER", "LANDSCAPER", "LENDING", "MANAGER", "MECHANIC", "MILITARY", "MORTICIAN", "NURSE", "NUTRITIONIST", "OFFICE", "PHARMACIST", "PHYSICAL", "PILOT", "POLICE", "POLITICIAN", "PM", "REP", "RESEARCHER", "SAILOR", "SALES", "SCIENTIST", "SEAMSTRESS", "SECURITY", "SOCIAL", "TEACHER", "TECHNICIAN", "TELLER", "TRADESPERSON", "TRAINER", "TRANSPORTER", "UNDERWRITER", "WRITER" ] }, "companyId": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "type": { "type": "string", "enum": [ "agriculture", "mining", "utilities", "construction", "manufacturing", "wholesale", "retail", "transport", "information", "finance", "realEstate", "professional", "management", "education", "health", "art", "food", "publicSector", "waste" ] }, "broker": { "type": "boolean" }, "directorOf": { "type": "string" } }, "required": [ "status", "broker", "directorOf" ] }, "identification": { "type": "object", "properties": { "taxIdType": { "type": "string", "enum": [ "ssn", "itin", "fein", "nino", "other" ] }, "taxId": { "type": "string", "minLength": 1 }, "issuingCountry": { "type": "string", "pattern": "^[A-Z]{3}$" }, "usTaxPayer": { "type": "boolean" } }, "required": [ "taxIdType", "taxId", "issuingCountry" ] }, "disclosures": { "type": "object", "properties": { "extendedHoursAgreement": { "type": "boolean" }, "termsOfUse": { "type": "boolean" }, "customerAgreement": { "type": "boolean" }, "iraAgreement": { "type": "boolean" }, "marginAgreement": { "type": "boolean" }, "cryptoAgreements": { "type": "boolean" }, "marketDataAgreement": { "type": "boolean" }, "optionsAgreement": { "type": "boolean" }, "rule14b": { "type": "boolean" }, "finderFee": { "type": "boolean" }, "privacyPolicy": { "type": "boolean" }, "dataSharing": { "type": "boolean" }, "signedBy": { "type": "string" } }, "required": [ "extendedHoursAgreement", "termsOfUse", "customerAgreement", "iraAgreement", "marginAgreement", "cryptoAgreements", "marketDataAgreement", "optionsAgreement", "rule14b", "finderFee", "privacyPolicy", "dataSharing", "signedBy" ] }, "investorProfile": { "type": "object", "properties": { "riskTolerance": { "type": "string", "enum": [ "low", "moderate", "speculation", "high" ] }, "investmentExperience": { "type": "string", "enum": [ "none", "yrs1Less", "yrs1To2", "yrs3To5", "yrs5To10", "yrs10Plus" ] }, "investmentObjectives": { "type": "string", "enum": [ "capitalPreservation", "income", "growth", "speculation" ] }, "annualIncome": { "type": "number", "minimum": 0 }, "totalNetWorth": { "type": "number", "minimum": 0 }, "liquidNetWorth": { "type": "number", "minimum": 0 }, "dependents": { "type": "integer", "minimum": 0 }, "suitabilityEquities": { "type": "string" }, "suitabilityOptions": { "type": "string" } }, "required": [ "annualIncome", "totalNetWorth" ] }, "taxInfo": { "type": "object", "properties": { "taxTreatyWithUS": { "type": "boolean" } } }, "status": { "type": "string", "enum": [ "notStarted", "inProgress", "ready", "submitted", "completed", "failed", "pending" ] }, "canSubmit": { "type": "boolean" }, "physicalDocuments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "side": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "uploaded", "approved", "rejected" ] }, "uploadedAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" } }, "required": [ "id", "type", "status" ] } }, "accountPreference": { "type": "string" }, "selectedPortfolioId": { "type": "string" }, "financialGoal": { "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "partnerId", "emailAddress", "kycStatus", "country", "language" ], "example": { "id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "partnerId": "partner_demo_001", "emailAddress": "integration.demo@client-example.com", "kycStatus": "inReview", "country": "USA", "language": "en_US", "personalInfo": { "birthDay": 15, "birthMonth": 8, "birthYear": 1985, "citizenship": "USA", "gender": "female", "maritalStatus": "single" }, "address": { "street1": "123 Integration Way", "city": "San Francisco", "province": "CA", "postalCode": "94105", "country": "USA" }, "status": "submitted", "canSubmit": false, "physicalDocuments": [ { "id": "doc_1abc2def", "type": "PASSPORT", "side": "FRONT", "status": "uploaded", "uploadedAt": "2023-10-27T14:30:00Z" } ], "accountPreference": "selfManaged", "financialGoal": "Long-term growth" } }, "SubmitOnboardingResponse": { "type": "object", "properties": { "personId": { "type": "string" } }, "required": [ "personId" ], "example": { "personId": "d290f1ee-6c54-4b01-90e6-d701748f0851" } }, "OpenAccountRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cash", "margin" ], "default": "cash" } }, "example": { "type": "cash" } }, "AccountResponse": { "type": "object", "properties": { "id": { "type": "string" }, "personId": { "type": "string" }, "partnerId": { "type": "string" }, "type": { "type": "string", "enum": [ "cash", "margin" ] }, "status": { "type": "string", "enum": [ "open", "openNoNewTrades", "closed", "frozen", "suspended", "pending" ] }, "openedAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" }, "closedAt": { "type": "string", "format": "date-time", "example": "2024-01-15T09:00:00Z" } }, "required": [ "id", "personId", "partnerId", "type", "status", "openedAt" ], "example": { "id": "acc_4f7b21a9", "personId": "d290f1ee-6c54-4b01-90e6-d701748f0851", "partnerId": "partner_demo_001", "type": "cash", "status": "open", "openedAt": "2023-10-27T14:30:00Z" } }, "AccountListResponse": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "personId": { "type": "string" }, "partnerId": { "type": "string" }, "type": { "type": "string", "enum": [ "cash", "margin" ] }, "status": { "type": "string", "enum": [ "open", "openNoNewTrades", "closed", "frozen", "suspended", "pending" ] }, "openedAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" }, "closedAt": { "type": "string", "format": "date-time", "example": "2024-01-15T09:00:00Z" } }, "required": [ "id", "personId", "partnerId", "type", "status", "openedAt" ], "example": { "id": "acc_4f7b21a9", "personId": "d290f1ee-6c54-4b01-90e6-d701748f0851", "partnerId": "partner_demo_001", "type": "cash", "status": "open", "openedAt": "2023-10-27T14:30:00Z" } } } }, "required": [ "accounts" ], "example": { "accounts": [ { "id": "acc_4f7b21a9", "personId": "d290f1ee-6c54-4b01-90e6-d701748f0851", "partnerId": "partner_demo_001", "type": "cash", "status": "open", "openedAt": "2023-10-27T14:30:00Z" } ] } }, "AccountBalanceResponse": { "type": "object", "properties": { "accountId": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." }, "settledCash": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ] }, "pendingCredits": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ] }, "pendingDebits": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ] }, "cashAvailable": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ] }, "asOf": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" } }, "required": [ "accountId", "currency", "settledCash", "pendingCredits", "pendingDebits", "cashAvailable", "asOf" ], "example": { "accountId": "acc_4f7b21a9", "currency": "USD", "settledCash": { "amount": 12500.45, "currency": "USD" }, "pendingCredits": { "amount": 250, "currency": "USD" }, "pendingDebits": { "amount": 0, "currency": "USD" }, "cashAvailable": { "amount": 12750.45, "currency": "USD" }, "asOf": "2023-10-27T14:30:00Z" } }, "CreateCashMovementRequest": { "type": "object", "properties": { "amount": { "type": "number", "exclusiveMinimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." }, "description": { "type": "string" }, "transferType": { "type": "string", "enum": [ "ach", "wire", "bulkFunding", "cashTransfer", "cashPromotion" ] } }, "required": [ "amount", "currency" ], "example": { "amount": 1500, "currency": "USD", "description": "Initial funding deposit", "transferType": "ach" } }, "MovementResponse": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "direction": { "type": "string", "enum": [ "credit", "debit" ] }, "amount": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ] }, "status": { "type": "string", "enum": [ "pending", "settled", "failed", "cancelled", "onHold", "returned", "requiresApproval" ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" }, "settledAt": { "type": "string", "format": "date-time", "example": "2023-10-29T10:00:00Z" }, "description": { "type": "string" } }, "required": [ "id", "accountId", "direction", "amount", "status", "createdAt" ], "example": { "id": "mov_8b3f6d21", "accountId": "acc_4f7b21a9", "direction": "credit", "amount": { "amount": 1500, "currency": "USD" }, "status": "settled", "createdAt": "2023-10-27T14:30:00Z", "settledAt": "2023-10-29T10:00:00Z", "description": "Initial funding deposit" } }, "MovementListResponse": { "type": "object", "properties": { "movements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "direction": { "type": "string", "enum": [ "credit", "debit" ] }, "amount": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ] }, "status": { "type": "string", "enum": [ "pending", "settled", "failed", "cancelled", "onHold", "returned", "requiresApproval" ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" }, "settledAt": { "type": "string", "format": "date-time", "example": "2023-10-29T10:00:00Z" }, "description": { "type": "string" } }, "required": [ "id", "accountId", "direction", "amount", "status", "createdAt" ], "example": { "id": "mov_8b3f6d21", "accountId": "acc_4f7b21a9", "direction": "credit", "amount": { "amount": 1500, "currency": "USD" }, "status": "settled", "createdAt": "2023-10-27T14:30:00Z", "settledAt": "2023-10-29T10:00:00Z", "description": "Initial funding deposit" } } } }, "required": [ "movements" ], "example": { "movements": [ { "id": "mov_8b3f6d21", "accountId": "acc_4f7b21a9", "direction": "credit", "amount": { "amount": 1500, "currency": "USD" }, "status": "settled", "createdAt": "2023-10-27T14:30:00Z", "settledAt": "2023-10-29T10:00:00Z", "description": "Initial funding deposit" } ] } }, "StageKycDocumentResponse": { "type": "object", "properties": { "documentId": { "type": "string", "description": "Internal reference ID for the staged document." }, "status": { "type": "string", "enum": [ "pending" ], "description": "Indicates the document is stored securely but not yet submitted to the upstream broker." } }, "required": [ "documentId", "status" ], "example": { "documentId": "doc_1abc2def", "status": "pending" } }, "UploadKycDocumentsResponse": { "type": "object", "properties": { "uploaded": { "type": "integer", "description": "The count of previously staged documents that were successfully transmitted to the upstream broker." }, "documents": { "type": "array", "items": { "type": "object", "properties": { "documentId": { "type": "string", "description": "The internal reference for the document that was uploaded." }, "status": { "type": "string", "description": "Status reported by the broker (e.g., uploaded, under_review)." } }, "required": [ "documentId", "status" ] }, "description": "Array of results for each document included in the transmission." } }, "required": [ "uploaded", "documents" ], "example": { "uploaded": 2, "documents": [ { "documentId": "doc_1abc2def", "status": "uploaded" }, { "documentId": "doc_3ghi4jkl", "status": "uploaded" } ] } }, "LinkFundingSourceRequest": { "type": "object", "properties": { "bankName": { "type": "string", "minLength": 1 }, "accountNumber": { "type": "string", "pattern": "^\\d{4,32}$" }, "routingNumber": { "type": "string", "pattern": "^\\d{9}$", "description": "Nine-digit ACH routing number. The current validation is tailored to US bank accounts and may not fit non-US settlement rails." }, "accountHolderName": { "type": "string", "minLength": 1 }, "accountType": { "type": "string", "enum": [ "checking", "savings" ], "default": "checking" }, "accountNickname": { "type": "string", "minLength": 1 }, "bankAddress": { "type": "string", "minLength": 1 }, "bankCountry": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 3166-1 alpha-3 country code for the linked bank account, used when the partner needs to distinguish domestic vs cross-border banking details." }, "bankAccountPurpose": { "type": "string", "enum": [ "travelRule", "settlementProfile" ], "description": "Purpose of the bank account linkage.\n- `travelRule`: Used strictly for linking external accounts to comply with Anti-Money Laundering (AML) verification rules.\n- `settlementProfile`: Used for active cash movement (deposits/withdrawals) between the external bank and the brokerage account." } }, "required": [ "bankName", "accountNumber", "routingNumber", "accountHolderName", "accountNickname" ], "additionalProperties": false, "example": { "bankName": "Chase Bank", "accountNumber": "1234567890", "routingNumber": "021000021", "accountHolderName": "Jane Doe", "accountType": "checking", "accountNickname": "Primary operating account", "bankCountry": "USA", "bankAccountPurpose": "settlementProfile" } }, "FundingSourceResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pendingVerify", "verified", "failed" ] }, "bankName": { "type": "string" }, "lastFourDigits": { "type": "string", "minLength": 4, "maxLength": 4 }, "routingNumber": { "type": "string", "minLength": 9, "maxLength": 9 }, "linkedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "accountId", "status", "bankName", "lastFourDigits", "routingNumber", "linkedAt" ], "additionalProperties": false, "example": { "id": "123e4567-e89b-12d3-a456-426614174000", "accountId": "223e4567-e89b-12d3-a456-426614174000", "status": "pendingVerify", "bankName": "Chase Bank", "lastFourDigits": "7890", "routingNumber": "021000021", "linkedAt": "2023-10-27T14:30:00.000Z" } }, "PlaceOrderRequest": { "type": "object", "properties": { "symbol": { "type": "string", "minLength": 1, "maxLength": 10, "description": "The tradable ticker symbol to submit to the broker, e.g. AAPL." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "Order side: buy or sell." }, "type": { "type": "string", "enum": [ "market", "limit" ], "description": "Execution type. Use `market` for immediate execution at prevailing prices or `limit` to cap the acceptable execution price." }, "quantity": { "type": "number", "exclusiveMinimum": 0, "description": "Number of shares to trade. Fractional quantities may be accepted when the underlying broker and instrument support them." }, "timeInForce": { "type": "string", "enum": [ "day", "gtc", "ioc", "fok" ], "description": "How long the order should remain active at the broker." }, "limitPrice": { "type": "number", "exclusiveMinimum": 0, "description": "Required when `type` is `limit`. Represents the highest buy price or lowest sell price the client is willing to accept." } }, "required": [ "symbol", "side", "type", "quantity", "timeInForce" ], "example": { "symbol": "AAPL", "side": "buy", "type": "market", "quantity": 1.5, "timeInForce": "day" } }, "OrderResponse": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "symbol": { "type": "string" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "type": { "type": "string", "enum": [ "market", "limit" ] }, "quantity": { "type": "number" }, "limitPrice": { "type": "number" }, "status": { "type": "string", "enum": [ "pending", "open", "filled", "cancelled", "rejected" ], "description": "Current broker order lifecycle status. Common values include pending, open, filled, cancelled, and rejected." }, "timeInForce": { "type": "string", "enum": [ "day", "gtc", "ioc", "fok" ] }, "placedAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" }, "filledAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:05Z" }, "cancelledAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:31:00Z" } }, "required": [ "id", "accountId", "symbol", "side", "type", "quantity", "status", "timeInForce", "placedAt" ], "example": { "id": "ord_123abc456", "accountId": "a8a8166c-240e-436f-b27b-e1b9b28b6d26", "symbol": "AAPL", "side": "buy", "type": "market", "quantity": 1.5, "status": "filled", "timeInForce": "day", "placedAt": "2023-10-27T14:30:00Z", "filledAt": "2023-10-27T14:30:05Z" } }, "OrderListResponse": { "type": "object", "properties": { "orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "symbol": { "type": "string" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "type": { "type": "string", "enum": [ "market", "limit" ] }, "quantity": { "type": "number" }, "limitPrice": { "type": "number" }, "status": { "type": "string", "enum": [ "pending", "open", "filled", "cancelled", "rejected" ], "description": "Current broker order lifecycle status. Common values include pending, open, filled, cancelled, and rejected." }, "timeInForce": { "type": "string", "enum": [ "day", "gtc", "ioc", "fok" ] }, "placedAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" }, "filledAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:05Z" }, "cancelledAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:31:00Z" } }, "required": [ "id", "accountId", "symbol", "side", "type", "quantity", "status", "timeInForce", "placedAt" ], "example": { "id": "ord_123abc456", "accountId": "a8a8166c-240e-436f-b27b-e1b9b28b6d26", "symbol": "AAPL", "side": "buy", "type": "market", "quantity": 1.5, "status": "filled", "timeInForce": "day", "placedAt": "2023-10-27T14:30:00Z", "filledAt": "2023-10-27T14:30:05Z" } } } }, "required": [ "orders" ], "example": { "orders": [ { "id": "ord_123abc456", "accountId": "a8a8166c-240e-436f-b27b-e1b9b28b6d26", "symbol": "AAPL", "side": "buy", "type": "market", "quantity": 1.5, "status": "filled", "timeInForce": "day", "placedAt": "2023-10-27T14:30:00Z", "filledAt": "2023-10-27T14:30:05Z" } ] } }, "PositionResponse": { "type": "object", "properties": { "accountBrokerId": { "type": "string", "description": "Broker-side account identifier." }, "symbol": { "type": "string", "description": "Tradable instrument symbol, e.g. AAPL." }, "quantity": { "type": "number", "description": "Current held quantity. Fractional values may be returned when the broker supports them." }, "costBasis": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ], "description": "Aggregate acquisition cost for the position." }, "marketValue": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ], "description": "Current marked-to-market value for the position." }, "asOf": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" } }, "required": [ "accountBrokerId", "symbol", "quantity", "costBasis", "marketValue", "asOf" ], "example": { "accountBrokerId": "dw-acct-001", "symbol": "AAPL", "quantity": 3.5, "costBasis": { "amount": 525.15, "currency": "USD" }, "marketValue": { "amount": 534.8, "currency": "USD" }, "asOf": "2023-10-27T14:30:00Z" } }, "PositionListResponse": { "type": "object", "properties": { "positions": { "type": "array", "items": { "type": "object", "properties": { "accountBrokerId": { "type": "string", "description": "Broker-side account identifier." }, "symbol": { "type": "string", "description": "Tradable instrument symbol, e.g. AAPL." }, "quantity": { "type": "number", "description": "Current held quantity. Fractional values may be returned when the broker supports them." }, "costBasis": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ], "description": "Aggregate acquisition cost for the position." }, "marketValue": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ], "description": "Current marked-to-market value for the position." }, "asOf": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" } }, "required": [ "accountBrokerId", "symbol", "quantity", "costBasis", "marketValue", "asOf" ], "example": { "accountBrokerId": "dw-acct-001", "symbol": "AAPL", "quantity": 3.5, "costBasis": { "amount": 525.15, "currency": "USD" }, "marketValue": { "amount": 534.8, "currency": "USD" }, "asOf": "2023-10-27T14:30:00Z" } } } }, "required": [ "positions" ], "example": { "positions": [ { "accountBrokerId": "dw-acct-001", "symbol": "AAPL", "quantity": 3.5, "costBasis": { "amount": 525.15, "currency": "USD" }, "marketValue": { "amount": 534.8, "currency": "USD" }, "asOf": "2023-10-27T14:30:00Z" } ] } }, "QuoteResponse": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Tradable instrument symbol, e.g. AAPL." }, "bid": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ], "description": "Best displayed bid price." }, "ask": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ], "description": "Best displayed ask price." }, "last": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ], "description": "Most recent traded price." }, "asOf": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" } }, "required": [ "symbol", "bid", "ask", "last", "asOf" ], "example": { "symbol": "AAPL", "bid": { "amount": 149.99, "currency": "USD" }, "ask": { "amount": 150.01, "currency": "USD" }, "last": { "amount": 150, "currency": "USD" }, "asOf": "2023-10-27T14:30:00Z" } }, "InstrumentResponse": { "type": "object", "properties": { "brokerId": { "type": "string", "description": "Broker-side instrument identifier." }, "symbol": { "type": "string", "description": "Tradable symbol returned by the broker." }, "name": { "type": "string", "description": "Human-readable instrument name." }, "type": { "type": "string", "enum": [ "equity", "etf", "option", "bond" ], "description": "High-level instrument category." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code for the instrument trading currency." }, "exchange": { "type": "string", "description": "Primary listing venue when available." }, "country": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 3166-1 alpha-3 country code when the broker provides it." } }, "required": [ "brokerId", "symbol", "name", "type", "currency" ], "example": { "brokerId": "inst-aapl-us", "symbol": "AAPL", "name": "Apple Inc.", "type": "equity", "currency": "USD", "exchange": "NASDAQ", "country": "USA" } }, "InstrumentListResponse": { "type": "object", "properties": { "instruments": { "type": "array", "items": { "type": "object", "properties": { "brokerId": { "type": "string", "description": "Broker-side instrument identifier." }, "symbol": { "type": "string", "description": "Tradable symbol returned by the broker." }, "name": { "type": "string", "description": "Human-readable instrument name." }, "type": { "type": "string", "enum": [ "equity", "etf", "option", "bond" ], "description": "High-level instrument category." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code for the instrument trading currency." }, "exchange": { "type": "string", "description": "Primary listing venue when available." }, "country": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 3166-1 alpha-3 country code when the broker provides it." } }, "required": [ "brokerId", "symbol", "name", "type", "currency" ], "example": { "brokerId": "inst-aapl-us", "symbol": "AAPL", "name": "Apple Inc.", "type": "equity", "currency": "USD", "exchange": "NASDAQ", "country": "USA" } } } }, "required": [ "instruments" ], "example": { "instruments": [ { "brokerId": "inst-aapl-us", "symbol": "AAPL", "name": "Apple Inc.", "type": "equity", "currency": "USD", "exchange": "NASDAQ", "country": "USA" } ] } } }, "parameters": {} }, "paths": { "/v1/accounts/{accountId}/balance": { "get": { "summary": "Get account cash balance from the movement ledger", "description": "Retrieves the current cash balance for the account, including settled cash, pending credits, pending debits, and the total cash available for trading.", "tags": [ "Accounts" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Internal account UUID" }, "required": true, "description": "Internal account UUID", "name": "accountId", "in": "path" } ], "responses": { "200": { "description": "Ledger-derived cash balance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." }, "settledCash": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ] }, "pendingCredits": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ] }, "pendingDebits": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ] }, "cashAvailable": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ] }, "asOf": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" } }, "required": [ "accountId", "currency", "settledCash", "pendingCredits", "pendingDebits", "cashAvailable", "asOf" ], "example": { "accountId": "acc_4f7b21a9", "currency": "USD", "settledCash": { "amount": 12500.45, "currency": "USD" }, "pendingCredits": { "amount": 250, "currency": "USD" }, "pendingDebits": { "amount": 0, "currency": "USD" }, "cashAvailable": { "amount": 12750.45, "currency": "USD" }, "asOf": "2023-10-27T14:30:00Z" } } } } }, "401": { "description": "Missing or invalid partner API key." }, "403": { "description": "Account does not belong to the authenticated partner." }, "404": { "description": "Account not found." } } } }, "/v1/accounts/{accountId}/deposits": { "post": { "summary": "Create a cash deposit", "description": "Creates a cash deposit movement for the specified account. Duplicate requests with the same `Idempotency-Key` replay the original successful response instead of creating a second side effect.", "tags": [ "Funding" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Internal account UUID" }, "required": true, "description": "Internal account UUID", "name": "accountId", "in": "path" }, { "schema": { "type": "string", "description": "Client-supplied idempotency key" }, "required": true, "description": "Client-supplied idempotency key", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "exclusiveMinimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." }, "description": { "type": "string" }, "transferType": { "type": "string", "enum": [ "ach", "bulkFunding", "cashPromotion", "cashTransfer" ], "description": "The method used to fund the account. Different options are available for deposits vs withdrawals.\n- `ACH`: Standard electronic bank transfer (requires a linked bank account).\n- `BULK_FUNDING`: Internal netting from the partner master settlement account.\n- `CASH_PROMOTION`: Partner-funded promotional credit or bonus.\n- `CASH_TRANSFER`: Internal transfer between two brokerage accounts under the same user." } }, "required": [ "amount", "currency" ], "example": { "amount": 1500, "currency": "USD", "description": "Initial funding deposit", "transferType": "ach" } } } } }, "responses": { "201": { "description": "Deposit movement created.", "headers": { "Idempotency-Replayed": { "description": "Present and set to true when the response body was replayed from the idempotency cache.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "direction": { "type": "string", "enum": [ "credit", "debit" ] }, "amount": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ] }, "status": { "type": "string", "enum": [ "pending", "settled", "failed", "cancelled", "onHold", "returned", "requiresApproval" ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" }, "settledAt": { "type": "string", "format": "date-time", "example": "2023-10-29T10:00:00Z" }, "description": { "type": "string" } }, "required": [ "id", "accountId", "direction", "amount", "status", "createdAt" ], "example": { "id": "mov_8b3f6d21", "accountId": "acc_4f7b21a9", "direction": "credit", "amount": { "amount": 1500, "currency": "USD" }, "status": "settled", "createdAt": "2023-10-27T14:30:00Z", "settledAt": "2023-10-29T10:00:00Z", "description": "Initial funding deposit" } } } } }, "400": { "description": "Invalid request. Missing or empty Idempotency-Key header." }, "401": { "description": "Missing or invalid partner API key." }, "403": { "description": "Account does not belong to the authenticated partner." }, "404": { "description": "Account not found." }, "502": { "description": "Upstream broker failure." } } } }, "/v1/accounts/{accountId}/withdrawals": { "post": { "summary": "Create a cash withdrawal", "description": "Creates a cash withdrawal movement for the specified account. Use `transferType = WIRE` only when the request also includes the full `wireDetails` object required by the destination bank. Duplicate requests with the same `Idempotency-Key` replay the original successful response instead of creating a second side effect.", "tags": [ "Funding" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Internal account UUID" }, "required": true, "description": "Internal account UUID", "name": "accountId", "in": "path" }, { "schema": { "type": "string", "description": "Client-supplied idempotency key" }, "required": true, "description": "Client-supplied idempotency key", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "exclusiveMinimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." }, "description": { "type": "string" }, "transferType": { "type": "string", "enum": [ "ach", "wire", "cashTransfer", "bulkFunding" ], "description": "The method used to withdraw funds from the account. Different options are available for withdrawals vs deposits.\n- `ACH`: Standard electronic bank transfer (requires a linked bank account).\n- `WIRE`: International or domestic wire transfer (requires `wireDetails` object).\n- `BULK_FUNDING`: Internal netting to the partner master settlement account.\n- `CASH_TRANSFER`: Internal transfer to another brokerage account under the same user." }, "wireDetails": { "type": "object", "properties": { "beneficiaryName": { "type": "string", "minLength": 1, "description": "Legal beneficiary name for the destination bank account." }, "beneficiaryAccountNumber": { "type": "string", "minLength": 1, "description": "Destination bank account number for the outgoing wire." }, "beneficiaryAccountType": { "type": "string", "enum": [ "checking", "savings" ], "description": "Destination account type for the outgoing wire." }, "beneficiaryRoutingNumber": { "type": "string", "minLength": 1, "description": "Domestic routing/transit number when the destination bank requires it." }, "beneficiarySwiftABA": { "type": "string", "minLength": 1, "description": "SWIFT or ABA identifier used by the receiving bank." }, "beneficiaryBankName": { "type": "string", "minLength": 1, "description": "Receiving bank legal name." }, "beneficiaryBankAddress": { "type": "string", "minLength": 1, "description": "Street address of the receiving bank." }, "beneficiaryBankCity": { "type": "string", "minLength": 1, "description": "City of the receiving bank." }, "beneficiaryBankProvince": { "type": "string", "minLength": 1, "description": "State, province, or region of the receiving bank." }, "beneficiaryBankZip": { "type": "string", "minLength": 1, "description": "Postal or ZIP code of the receiving bank." }, "beneficiaryBankCountry": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 3166-1 alpha-3 country code for the receiving bank." }, "intermediarySwift": { "type": "string" }, "intermediaryBankName": { "type": "string" } }, "required": [ "beneficiaryName", "beneficiaryAccountNumber", "beneficiaryAccountType", "beneficiaryRoutingNumber", "beneficiarySwiftABA", "beneficiaryBankName", "beneficiaryBankAddress", "beneficiaryBankCity", "beneficiaryBankProvince", "beneficiaryBankZip", "beneficiaryBankCountry" ], "description": "Required when `transferType` is `WIRE`. Omit it for ACH, BULK_FUNDING, and CASH_TRANSFER withdrawals because the field is ignored for those transfer types." } }, "required": [ "amount", "currency" ], "example": { "amount": 500, "currency": "USD", "description": "Monthly cash withdrawal", "transferType": "ach" } } } } }, "responses": { "201": { "description": "Withdrawal movement created.", "headers": { "Idempotency-Replayed": { "description": "Present and set to true when the response body was replayed from the idempotency cache.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "direction": { "type": "string", "enum": [ "credit", "debit" ] }, "amount": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ] }, "status": { "type": "string", "enum": [ "pending", "settled", "failed", "cancelled", "onHold", "returned", "requiresApproval" ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" }, "settledAt": { "type": "string", "format": "date-time", "example": "2023-10-29T10:00:00Z" }, "description": { "type": "string" } }, "required": [ "id", "accountId", "direction", "amount", "status", "createdAt" ], "example": { "id": "mov_8b3f6d21", "accountId": "acc_4f7b21a9", "direction": "credit", "amount": { "amount": 1500, "currency": "USD" }, "status": "settled", "createdAt": "2023-10-27T14:30:00Z", "settledAt": "2023-10-29T10:00:00Z", "description": "Initial funding deposit" } } } } }, "400": { "description": "Invalid request, insufficient cash, or missing or empty idempotency-key header." }, "401": { "description": "Missing or invalid partner API key." }, "403": { "description": "Account does not belong to the authenticated partner." }, "404": { "description": "Account not found." }, "502": { "description": "Upstream broker failure." } } } }, "/v1/accounts/{accountId}/funding-sources": { "post": { "summary": "Link a bank funding source to an account", "description": "Links an external bank account that can later be used for ACH-based funding flows. The current request validation is tailored to US routing numbers, so non-US banking rails may require a future contract extension. Duplicate requests with the same `Idempotency-Key` replay the original successful response instead of creating a second side effect.", "tags": [ "Funding" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Internal account UUID" }, "required": true, "description": "Internal account UUID", "name": "accountId", "in": "path" }, { "schema": { "type": "string", "description": "Client-supplied idempotency key (required)" }, "required": true, "description": "Client-supplied idempotency key (required)", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankName": { "type": "string", "minLength": 1 }, "accountNumber": { "type": "string", "pattern": "^\\d{4,32}$" }, "routingNumber": { "type": "string", "pattern": "^\\d{9}$", "description": "Nine-digit ACH routing number. The current validation is tailored to US bank accounts and may not fit non-US settlement rails." }, "accountHolderName": { "type": "string", "minLength": 1 }, "accountType": { "type": "string", "enum": [ "checking", "savings" ], "default": "checking" }, "accountNickname": { "type": "string", "minLength": 1 }, "bankAddress": { "type": "string", "minLength": 1 }, "bankCountry": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 3166-1 alpha-3 country code for the linked bank account, used when the partner needs to distinguish domestic vs cross-border banking details." }, "bankAccountPurpose": { "type": "string", "enum": [ "travelRule", "settlementProfile" ], "description": "Purpose of the bank account linkage.\n- `travelRule`: Used strictly for linking external accounts to comply with Anti-Money Laundering (AML) verification rules.\n- `settlementProfile`: Used for active cash movement (deposits/withdrawals) between the external bank and the brokerage account." } }, "required": [ "bankName", "accountNumber", "routingNumber", "accountHolderName", "accountNickname" ], "additionalProperties": false, "example": { "bankName": "Chase Bank", "accountNumber": "1234567890", "routingNumber": "021000021", "accountHolderName": "Jane Doe", "accountType": "checking", "accountNickname": "Primary operating account", "bankCountry": "USA", "bankAccountPurpose": "settlementProfile" } } } } }, "responses": { "201": { "description": "Funding source linked (or pending if broker not available).", "headers": { "Idempotency-Replayed": { "description": "Present and set to true when the response body was replayed from the idempotency cache.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pendingVerify", "verified", "failed" ] }, "bankName": { "type": "string" }, "lastFourDigits": { "type": "string", "minLength": 4, "maxLength": 4 }, "routingNumber": { "type": "string", "minLength": 9, "maxLength": 9 }, "linkedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "accountId", "status", "bankName", "lastFourDigits", "routingNumber", "linkedAt" ], "additionalProperties": false, "example": { "id": "123e4567-e89b-12d3-a456-426614174000", "accountId": "223e4567-e89b-12d3-a456-426614174000", "status": "pendingVerify", "bankName": "Chase Bank", "lastFourDigits": "7890", "routingNumber": "021000021", "linkedAt": "2023-10-27T14:30:00.000Z" } } } } }, "400": { "description": "Invalid request, invalid account/routing number format, or missing or empty idempotency-key header." }, "401": { "description": "Missing or invalid partner API key." }, "403": { "description": "Account does not belong to the authenticated partner." }, "404": { "description": "Account not found." }, "502": { "description": "Upstream broker failure." } } } }, "/v1/accounts/{accountId}/movements": { "get": { "summary": "List account cash movements", "tags": [ "Funding" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Internal account UUID" }, "required": true, "description": "Internal account UUID", "name": "accountId", "in": "path" } ], "responses": { "200": { "description": "Cash movements for the account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "movements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "direction": { "type": "string", "enum": [ "credit", "debit" ] }, "amount": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ] }, "status": { "type": "string", "enum": [ "pending", "settled", "failed", "cancelled", "onHold", "returned", "requiresApproval" ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" }, "settledAt": { "type": "string", "format": "date-time", "example": "2023-10-29T10:00:00Z" }, "description": { "type": "string" } }, "required": [ "id", "accountId", "direction", "amount", "status", "createdAt" ], "example": { "id": "mov_8b3f6d21", "accountId": "acc_4f7b21a9", "direction": "credit", "amount": { "amount": 1500, "currency": "USD" }, "status": "settled", "createdAt": "2023-10-27T14:30:00Z", "settledAt": "2023-10-29T10:00:00Z", "description": "Initial funding deposit" } } } }, "required": [ "movements" ], "example": { "movements": [ { "id": "mov_8b3f6d21", "accountId": "acc_4f7b21a9", "direction": "credit", "amount": { "amount": 1500, "currency": "USD" }, "status": "settled", "createdAt": "2023-10-27T14:30:00Z", "settledAt": "2023-10-29T10:00:00Z", "description": "Initial funding deposit" } ] } } } } }, "401": { "description": "Missing or invalid partner API key." }, "403": { "description": "Account does not belong to the authenticated partner." }, "404": { "description": "Account not found." } } } }, "/v1/movements/{movementId}": { "get": { "summary": "Get a cash movement", "tags": [ "Funding" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Internal movement UUID" }, "required": true, "description": "Internal movement UUID", "name": "movementId", "in": "path" } ], "responses": { "200": { "description": "Cash movement details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "direction": { "type": "string", "enum": [ "credit", "debit" ] }, "amount": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ] }, "status": { "type": "string", "enum": [ "pending", "settled", "failed", "cancelled", "onHold", "returned", "requiresApproval" ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" }, "settledAt": { "type": "string", "format": "date-time", "example": "2023-10-29T10:00:00Z" }, "description": { "type": "string" } }, "required": [ "id", "accountId", "direction", "amount", "status", "createdAt" ], "example": { "id": "mov_8b3f6d21", "accountId": "acc_4f7b21a9", "direction": "credit", "amount": { "amount": 1500, "currency": "USD" }, "status": "settled", "createdAt": "2023-10-27T14:30:00Z", "settledAt": "2023-10-29T10:00:00Z", "description": "Initial funding deposit" } } } } }, "401": { "description": "Missing or invalid partner API key." }, "403": { "description": "Movement does not belong to the authenticated partner." }, "404": { "description": "Movement not found." } } } }, "/livez": { "get": { "summary": "Liveness probe", "description": "Returns basic process health without verifying downstream dependencies.", "tags": [ "Health" ], "responses": { "200": { "description": "Service process is alive.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "uptimeSeconds": { "type": "integer", "minimum": 0 }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "status", "uptimeSeconds", "timestamp" ], "example": { "status": "ok", "uptimeSeconds": 3600, "timestamp": "2023-10-27T14:30:00.000Z" } } } } } } } }, "/readyz": { "get": { "summary": "Readiness probe", "description": "Returns whether the application is ready to serve traffic and can reach the database.", "tags": [ "Health" ], "responses": { "200": { "description": "Application is ready to serve traffic.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "notReady" ] }, "isReady": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" }, "checks": { "type": "object", "properties": { "dataSourceInitialized": { "type": "boolean" }, "databaseReachable": { "type": "boolean" } }, "required": [ "dataSourceInitialized", "databaseReachable" ] } }, "required": [ "status", "isReady", "timestamp", "checks" ], "example": { "status": "ok", "isReady": true, "timestamp": "2023-10-27T14:30:00.000Z", "checks": { "dataSourceInitialized": true, "databaseReachable": true } } } } } }, "503": { "description": "Application is not ready to serve traffic.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "notReady" ] }, "isReady": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" }, "checks": { "type": "object", "properties": { "dataSourceInitialized": { "type": "boolean" }, "databaseReachable": { "type": "boolean" } }, "required": [ "dataSourceInitialized", "databaseReachable" ] } }, "required": [ "status", "isReady", "timestamp", "checks" ], "example": { "status": "ok", "isReady": true, "timestamp": "2023-10-27T14:30:00.000Z", "checks": { "dataSourceInitialized": true, "databaseReachable": true } } } } } } } } }, "/v1/persons": { "post": { "summary": "Register a person", "description": "Creates a new partner-scoped person record and can include onboarding categories in the same request. Duplicate requests with the same `Idempotency-Key` replay the original successful response instead of creating a second side effect.", "tags": [ "Person" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Unique key supplied by the client to safely retry the request without duplicating side effects." }, "required": true, "description": "Unique key supplied by the client to safely retry the request without duplicating side effects.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1 }, "lastName": { "type": "string", "minLength": 1 }, "country": { "type": "string", "pattern": "^[A-Z]{3}$" }, "phone": { "type": "string", "minLength": 1 }, "emailAddress": { "type": "string", "format": "email" }, "language": { "type": "string", "enum": [ "en_US", "zh_CN", "es_ES", "pt_BR" ] }, "userType": { "type": "string", "enum": [ "individualTrader", "custodial" ] }, "personalInfo": { "type": "object", "properties": { "birthDay": { "type": "integer", "minimum": 1, "maximum": 31 }, "birthMonth": { "type": "integer", "minimum": 1, "maximum": 12 }, "birthYear": { "type": "integer", "minimum": 1900 }, "citizenship": { "type": "string", "pattern": "^[A-Z]{3}$" }, "politicallyExposedNames": { "type": "string" }, "irsBackupWithholdings": { "type": "boolean" }, "gender": { "type": "string", "enum": [ "male", "female" ] }, "maritalStatus": { "type": "string", "enum": [ "single", "divorced", "married", "widowed", "partner" ] } }, "required": [ "birthDay", "birthMonth", "birthYear", "citizenship" ] }, "address": { "type": "object", "properties": { "street1": { "type": "string", "minLength": 1 }, "street2": { "type": "string" }, "city": { "type": "string", "minLength": 1 }, "province": { "type": "string", "minLength": 1 }, "postalCode": { "type": "string", "minLength": 1 }, "country": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "street1", "city", "province", "postalCode", "country" ] }, "employment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "employed", "selfEmployed", "unemployed", "retired", "student" ] }, "employerName": { "type": "string" }, "occupation": { "type": "string", "enum": [ "ACCOUNTANT", "ACTUARY", "ADJUSTER", "ADMINISTRATOR", "ADVERTISER", "AGENT", "ATC", "AMBASSADOR", "ANALYST", "APPRAISER", "ARCHITECT", "ARTIST", "ASSISTANT", "ATHLETE", "ATTENDANT", "ATTORNEY", "AUCTIONEER", "AUDITOR", "BARBER", "BROKER", "BUSINESS_EXEC", "BUSINESS_OWNER", "CAREGIVER", "CARPENTER", "CASHIER", "CHEF", "CHIROPRACTOR", "CIVIL", "CLERGY", "CLERK", "COMPLIANCE", "CONSULTANT", "CONTRACTOR", "COUNSELOR", "CUSTOMER_SERVICE", "DEALER", "DEVELOPER", "DISTRIBUTOR", "DOCTOR", "DRIVER", "ENGINEER", "EXAMINER", "EXTERMINATOR", "FACTORY", "FARMER", "FINANCIAL", "FISHERMAN", "FLIGHT", "HR", "IMPEX", "INSPECTOR", "INTERN", "INVESTMENT", "INVESTOR", "IT", "JANITOR", "JEWELER", "LABORER", "LANDSCAPER", "LENDING", "MANAGER", "MECHANIC", "MILITARY", "MORTICIAN", "NURSE", "NUTRITIONIST", "OFFICE", "PHARMACIST", "PHYSICAL", "PILOT", "POLICE", "POLITICIAN", "PM", "REP", "RESEARCHER", "SAILOR", "SALES", "SCIENTIST", "SEAMSTRESS", "SECURITY", "SOCIAL", "TEACHER", "TECHNICIAN", "TELLER", "TRADESPERSON", "TRAINER", "TRANSPORTER", "UNDERWRITER", "WRITER" ] }, "companyId": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "type": { "type": "string", "enum": [ "agriculture", "mining", "utilities", "construction", "manufacturing", "wholesale", "retail", "transport", "information", "finance", "realEstate", "professional", "management", "education", "health", "art", "food", "publicSector", "waste" ] }, "broker": { "type": "boolean" }, "directorOf": { "type": "string" } }, "required": [ "status", "broker", "directorOf" ] }, "identification": { "type": "object", "properties": { "taxIdType": { "type": "string", "enum": [ "ssn", "itin", "fein", "nino", "other" ] }, "taxId": { "type": "string", "minLength": 1 }, "issuingCountry": { "type": "string", "pattern": "^[A-Z]{3}$" }, "usTaxPayer": { "type": "boolean" } }, "required": [ "taxIdType", "taxId", "issuingCountry" ] }, "disclosures": { "type": "object", "properties": { "extendedHoursAgreement": { "type": "boolean" }, "termsOfUse": { "type": "boolean" }, "customerAgreement": { "type": "boolean" }, "iraAgreement": { "type": "boolean" }, "marginAgreement": { "type": "boolean" }, "cryptoAgreements": { "type": "boolean" }, "marketDataAgreement": { "type": "boolean" }, "optionsAgreement": { "type": "boolean" }, "rule14b": { "type": "boolean" }, "finderFee": { "type": "boolean" }, "privacyPolicy": { "type": "boolean" }, "dataSharing": { "type": "boolean" }, "signedBy": { "type": "string" } }, "required": [ "extendedHoursAgreement", "termsOfUse", "customerAgreement", "iraAgreement", "marginAgreement", "cryptoAgreements", "marketDataAgreement", "optionsAgreement", "rule14b", "finderFee", "privacyPolicy", "dataSharing", "signedBy" ] }, "investorProfile": { "type": "object", "properties": { "riskTolerance": { "type": "string", "enum": [ "low", "moderate", "speculation", "high" ] }, "investmentExperience": { "type": "string", "enum": [ "none", "yrs1Less", "yrs1To2", "yrs3To5", "yrs5To10", "yrs10Plus" ] }, "investmentObjectives": { "type": "string", "enum": [ "capitalPreservation", "income", "growth", "speculation" ] }, "annualIncome": { "type": "number", "minimum": 0 }, "totalNetWorth": { "type": "number", "minimum": 0 }, "liquidNetWorth": { "type": "number", "minimum": 0 }, "dependents": { "type": "integer", "minimum": 0 }, "suitabilityEquities": { "type": "string" }, "suitabilityOptions": { "type": "string" } }, "required": [ "annualIncome", "totalNetWorth" ] }, "taxInfo": { "type": "object", "properties": { "taxTreatyWithUS": { "type": "boolean" } } } }, "required": [ "firstName", "lastName", "country", "phone", "emailAddress", "language", "userType" ], "example": { "firstName": "Jane", "lastName": "Doe", "country": "USA", "phone": "+15550100123", "emailAddress": "integration.demo@client-example.com", "language": "en_US", "userType": "individualTrader", "address": { "street1": "123 Integration Way", "city": "San Francisco", "province": "CA", "postalCode": "94105", "country": "USA" } } } } } }, "responses": { "201": { "description": "Person created successfully.", "headers": { "Idempotency-Replayed": { "description": "Present and set to true when the response body was replayed from the idempotency cache.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "partnerId": { "type": "string" }, "emailAddress": { "type": "string", "format": "email" }, "kycStatus": { "type": "string", "enum": [ "pending", "inReview", "needsMoreInfo", "approved", "rejected", "expired" ] }, "country": { "type": "string", "pattern": "^[A-Z]{3}$" }, "language": { "type": "string" }, "personalInfo": { "type": "object", "properties": { "birthDay": { "type": "integer", "minimum": 1, "maximum": 31 }, "birthMonth": { "type": "integer", "minimum": 1, "maximum": 12 }, "birthYear": { "type": "integer", "minimum": 1900 }, "citizenship": { "type": "string", "pattern": "^[A-Z]{3}$" }, "politicallyExposedNames": { "type": "string" }, "irsBackupWithholdings": { "type": "boolean" }, "gender": { "type": "string", "enum": [ "male", "female" ] }, "maritalStatus": { "type": "string", "enum": [ "single", "divorced", "married", "widowed", "partner" ] } }, "required": [ "birthDay", "birthMonth", "birthYear", "citizenship" ] }, "address": { "type": "object", "properties": { "street1": { "type": "string", "minLength": 1 }, "street2": { "type": "string" }, "city": { "type": "string", "minLength": 1 }, "province": { "type": "string", "minLength": 1 }, "postalCode": { "type": "string", "minLength": 1 }, "country": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "street1", "city", "province", "postalCode", "country" ] }, "employment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "employed", "selfEmployed", "unemployed", "retired", "student" ] }, "employerName": { "type": "string" }, "occupation": { "type": "string", "enum": [ "ACCOUNTANT", "ACTUARY", "ADJUSTER", "ADMINISTRATOR", "ADVERTISER", "AGENT", "ATC", "AMBASSADOR", "ANALYST", "APPRAISER", "ARCHITECT", "ARTIST", "ASSISTANT", "ATHLETE", "ATTENDANT", "ATTORNEY", "AUCTIONEER", "AUDITOR", "BARBER", "BROKER", "BUSINESS_EXEC", "BUSINESS_OWNER", "CAREGIVER", "CARPENTER", "CASHIER", "CHEF", "CHIROPRACTOR", "CIVIL", "CLERGY", "CLERK", "COMPLIANCE", "CONSULTANT", "CONTRACTOR", "COUNSELOR", "CUSTOMER_SERVICE", "DEALER", "DEVELOPER", "DISTRIBUTOR", "DOCTOR", "DRIVER", "ENGINEER", "EXAMINER", "EXTERMINATOR", "FACTORY", "FARMER", "FINANCIAL", "FISHERMAN", "FLIGHT", "HR", "IMPEX", "INSPECTOR", "INTERN", "INVESTMENT", "INVESTOR", "IT", "JANITOR", "JEWELER", "LABORER", "LANDSCAPER", "LENDING", "MANAGER", "MECHANIC", "MILITARY", "MORTICIAN", "NURSE", "NUTRITIONIST", "OFFICE", "PHARMACIST", "PHYSICAL", "PILOT", "POLICE", "POLITICIAN", "PM", "REP", "RESEARCHER", "SAILOR", "SALES", "SCIENTIST", "SEAMSTRESS", "SECURITY", "SOCIAL", "TEACHER", "TECHNICIAN", "TELLER", "TRADESPERSON", "TRAINER", "TRANSPORTER", "UNDERWRITER", "WRITER" ] }, "companyId": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "type": { "type": "string", "enum": [ "agriculture", "mining", "utilities", "construction", "manufacturing", "wholesale", "retail", "transport", "information", "finance", "realEstate", "professional", "management", "education", "health", "art", "food", "publicSector", "waste" ] }, "broker": { "type": "boolean" }, "directorOf": { "type": "string" } }, "required": [ "status", "broker", "directorOf" ] }, "identification": { "type": "object", "properties": { "taxIdType": { "type": "string", "enum": [ "ssn", "itin", "fein", "nino", "other" ] }, "taxId": { "type": "string", "minLength": 1 }, "issuingCountry": { "type": "string", "pattern": "^[A-Z]{3}$" }, "usTaxPayer": { "type": "boolean" } }, "required": [ "taxIdType", "taxId", "issuingCountry" ] }, "disclosures": { "type": "object", "properties": { "extendedHoursAgreement": { "type": "boolean" }, "termsOfUse": { "type": "boolean" }, "customerAgreement": { "type": "boolean" }, "iraAgreement": { "type": "boolean" }, "marginAgreement": { "type": "boolean" }, "cryptoAgreements": { "type": "boolean" }, "marketDataAgreement": { "type": "boolean" }, "optionsAgreement": { "type": "boolean" }, "rule14b": { "type": "boolean" }, "finderFee": { "type": "boolean" }, "privacyPolicy": { "type": "boolean" }, "dataSharing": { "type": "boolean" }, "signedBy": { "type": "string" } }, "required": [ "extendedHoursAgreement", "termsOfUse", "customerAgreement", "iraAgreement", "marginAgreement", "cryptoAgreements", "marketDataAgreement", "optionsAgreement", "rule14b", "finderFee", "privacyPolicy", "dataSharing", "signedBy" ] }, "investorProfile": { "type": "object", "properties": { "riskTolerance": { "type": "string", "enum": [ "low", "moderate", "speculation", "high" ] }, "investmentExperience": { "type": "string", "enum": [ "none", "yrs1Less", "yrs1To2", "yrs3To5", "yrs5To10", "yrs10Plus" ] }, "investmentObjectives": { "type": "string", "enum": [ "capitalPreservation", "income", "growth", "speculation" ] }, "annualIncome": { "type": "number", "minimum": 0 }, "totalNetWorth": { "type": "number", "minimum": 0 }, "liquidNetWorth": { "type": "number", "minimum": 0 }, "dependents": { "type": "integer", "minimum": 0 }, "suitabilityEquities": { "type": "string" }, "suitabilityOptions": { "type": "string" } }, "required": [ "annualIncome", "totalNetWorth" ] }, "taxInfo": { "type": "object", "properties": { "taxTreatyWithUS": { "type": "boolean" } } }, "status": { "type": "string", "enum": [ "notStarted", "inProgress", "ready", "submitted", "completed", "failed", "pending" ] }, "canSubmit": { "type": "boolean" }, "physicalDocuments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "side": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "uploaded", "approved", "rejected" ] }, "uploadedAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" } }, "required": [ "id", "type", "status" ] } }, "accountPreference": { "type": "string" }, "selectedPortfolioId": { "type": "string" }, "financialGoal": { "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "partnerId", "emailAddress", "kycStatus", "country", "language" ], "example": { "id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "partnerId": "partner_demo_001", "emailAddress": "integration.demo@client-example.com", "kycStatus": "inReview", "country": "USA", "language": "en_US", "personalInfo": { "birthDay": 15, "birthMonth": 8, "birthYear": 1985, "citizenship": "USA", "gender": "female", "maritalStatus": "single" }, "address": { "street1": "123 Integration Way", "city": "San Francisco", "province": "CA", "postalCode": "94105", "country": "USA" }, "status": "submitted", "canSubmit": false, "physicalDocuments": [ { "id": "doc_1abc2def", "type": "PASSPORT", "side": "FRONT", "status": "uploaded", "uploadedAt": "2023-10-27T14:30:00Z" } ], "accountPreference": "selfManaged", "financialGoal": "Long-term growth" } } } } }, "400": { "description": "Invalid body or missing or empty idempotency-key header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "array", "items": {} } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, or expired partner API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Authenticated partner is suspended.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "409": { "description": "A conflicting person record already exists for the partner.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "422": { "description": "Body is structurally valid but fails domain validation rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "502": { "description": "Broker-side registration failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/persons/{personId}": { "patch": { "summary": "Update a person", "description": "Updates onboarding categories for an existing person. Immutable basic identity fields are not accepted on this endpoint. Clients may send one or more complete category objects in the same request, but when a category is included it replaces that category as a whole rather than applying a field-by-field JSON merge.", "tags": [ "Person" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Internal person UUID" }, "required": true, "description": "Internal person UUID", "name": "personId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "personalInfo": { "type": "object", "properties": { "birthDay": { "type": "integer", "minimum": 1, "maximum": 31 }, "birthMonth": { "type": "integer", "minimum": 1, "maximum": 12 }, "birthYear": { "type": "integer", "minimum": 1900 }, "citizenship": { "type": "string", "pattern": "^[A-Z]{3}$" }, "politicallyExposedNames": { "type": "string" }, "irsBackupWithholdings": { "type": "boolean" }, "gender": { "type": "string", "enum": [ "male", "female" ] }, "maritalStatus": { "type": "string", "enum": [ "single", "divorced", "married", "widowed", "partner" ] } }, "required": [ "birthDay", "birthMonth", "birthYear", "citizenship" ] }, "address": { "type": "object", "properties": { "street1": { "type": "string", "minLength": 1 }, "street2": { "type": "string" }, "city": { "type": "string", "minLength": 1 }, "province": { "type": "string", "minLength": 1 }, "postalCode": { "type": "string", "minLength": 1 }, "country": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "street1", "city", "province", "postalCode", "country" ] }, "employment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "employed", "selfEmployed", "unemployed", "retired", "student" ] }, "employerName": { "type": "string" }, "occupation": { "type": "string", "enum": [ "ACCOUNTANT", "ACTUARY", "ADJUSTER", "ADMINISTRATOR", "ADVERTISER", "AGENT", "ATC", "AMBASSADOR", "ANALYST", "APPRAISER", "ARCHITECT", "ARTIST", "ASSISTANT", "ATHLETE", "ATTENDANT", "ATTORNEY", "AUCTIONEER", "AUDITOR", "BARBER", "BROKER", "BUSINESS_EXEC", "BUSINESS_OWNER", "CAREGIVER", "CARPENTER", "CASHIER", "CHEF", "CHIROPRACTOR", "CIVIL", "CLERGY", "CLERK", "COMPLIANCE", "CONSULTANT", "CONTRACTOR", "COUNSELOR", "CUSTOMER_SERVICE", "DEALER", "DEVELOPER", "DISTRIBUTOR", "DOCTOR", "DRIVER", "ENGINEER", "EXAMINER", "EXTERMINATOR", "FACTORY", "FARMER", "FINANCIAL", "FISHERMAN", "FLIGHT", "HR", "IMPEX", "INSPECTOR", "INTERN", "INVESTMENT", "INVESTOR", "IT", "JANITOR", "JEWELER", "LABORER", "LANDSCAPER", "LENDING", "MANAGER", "MECHANIC", "MILITARY", "MORTICIAN", "NURSE", "NUTRITIONIST", "OFFICE", "PHARMACIST", "PHYSICAL", "PILOT", "POLICE", "POLITICIAN", "PM", "REP", "RESEARCHER", "SAILOR", "SALES", "SCIENTIST", "SEAMSTRESS", "SECURITY", "SOCIAL", "TEACHER", "TECHNICIAN", "TELLER", "TRADESPERSON", "TRAINER", "TRANSPORTER", "UNDERWRITER", "WRITER" ] }, "companyId": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "type": { "type": "string", "enum": [ "agriculture", "mining", "utilities", "construction", "manufacturing", "wholesale", "retail", "transport", "information", "finance", "realEstate", "professional", "management", "education", "health", "art", "food", "publicSector", "waste" ] }, "broker": { "type": "boolean" }, "directorOf": { "type": "string" } }, "required": [ "status", "broker", "directorOf" ] }, "identification": { "type": "object", "properties": { "taxIdType": { "type": "string", "enum": [ "ssn", "itin", "fein", "nino", "other" ] }, "taxId": { "type": "string", "minLength": 1 }, "issuingCountry": { "type": "string", "pattern": "^[A-Z]{3}$" }, "usTaxPayer": { "type": "boolean" } }, "required": [ "taxIdType", "taxId", "issuingCountry" ] }, "disclosures": { "type": "object", "properties": { "extendedHoursAgreement": { "type": "boolean" }, "termsOfUse": { "type": "boolean" }, "customerAgreement": { "type": "boolean" }, "iraAgreement": { "type": "boolean" }, "marginAgreement": { "type": "boolean" }, "cryptoAgreements": { "type": "boolean" }, "marketDataAgreement": { "type": "boolean" }, "optionsAgreement": { "type": "boolean" }, "rule14b": { "type": "boolean" }, "finderFee": { "type": "boolean" }, "privacyPolicy": { "type": "boolean" }, "dataSharing": { "type": "boolean" }, "signedBy": { "type": "string" } }, "required": [ "extendedHoursAgreement", "termsOfUse", "customerAgreement", "iraAgreement", "marginAgreement", "cryptoAgreements", "marketDataAgreement", "optionsAgreement", "rule14b", "finderFee", "privacyPolicy", "dataSharing", "signedBy" ] }, "investorProfile": { "type": "object", "properties": { "riskTolerance": { "type": "string", "enum": [ "low", "moderate", "speculation", "high" ] }, "investmentExperience": { "type": "string", "enum": [ "none", "yrs1Less", "yrs1To2", "yrs3To5", "yrs5To10", "yrs10Plus" ] }, "investmentObjectives": { "type": "string", "enum": [ "capitalPreservation", "income", "growth", "speculation" ] }, "annualIncome": { "type": "number", "minimum": 0 }, "totalNetWorth": { "type": "number", "minimum": 0 }, "liquidNetWorth": { "type": "number", "minimum": 0 }, "dependents": { "type": "integer", "minimum": 0 }, "suitabilityEquities": { "type": "string" }, "suitabilityOptions": { "type": "string" } }, "required": [ "annualIncome", "totalNetWorth" ] }, "taxInfo": { "type": "object", "properties": { "taxTreatyWithUS": { "type": "boolean" } } } }, "description": "Partial update payload for onboarding categories. Clients may send one or more complete category objects in the same request. When a category is included, all required fields for that category must be supplied together because category updates are applied with replace semantics rather than field-by-field patch semantics.", "example": { "personalInfo": { "birthDay": 15, "birthMonth": 8, "birthYear": 1985, "citizenship": "USA", "gender": "female", "maritalStatus": "single" }, "employment": { "status": "employed", "employerName": "Acme Corp", "occupation": "ENGINEER", "from": "2020", "broker": false, "directorOf": "Acme Ventures LLC" } } } } } }, "responses": { "200": { "description": "Person updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "partnerId": { "type": "string" }, "emailAddress": { "type": "string", "format": "email" }, "kycStatus": { "type": "string", "enum": [ "pending", "inReview", "needsMoreInfo", "approved", "rejected", "expired" ] }, "country": { "type": "string", "pattern": "^[A-Z]{3}$" }, "language": { "type": "string" }, "personalInfo": { "type": "object", "properties": { "birthDay": { "type": "integer", "minimum": 1, "maximum": 31 }, "birthMonth": { "type": "integer", "minimum": 1, "maximum": 12 }, "birthYear": { "type": "integer", "minimum": 1900 }, "citizenship": { "type": "string", "pattern": "^[A-Z]{3}$" }, "politicallyExposedNames": { "type": "string" }, "irsBackupWithholdings": { "type": "boolean" }, "gender": { "type": "string", "enum": [ "male", "female" ] }, "maritalStatus": { "type": "string", "enum": [ "single", "divorced", "married", "widowed", "partner" ] } }, "required": [ "birthDay", "birthMonth", "birthYear", "citizenship" ] }, "address": { "type": "object", "properties": { "street1": { "type": "string", "minLength": 1 }, "street2": { "type": "string" }, "city": { "type": "string", "minLength": 1 }, "province": { "type": "string", "minLength": 1 }, "postalCode": { "type": "string", "minLength": 1 }, "country": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "street1", "city", "province", "postalCode", "country" ] }, "employment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "employed", "selfEmployed", "unemployed", "retired", "student" ] }, "employerName": { "type": "string" }, "occupation": { "type": "string", "enum": [ "ACCOUNTANT", "ACTUARY", "ADJUSTER", "ADMINISTRATOR", "ADVERTISER", "AGENT", "ATC", "AMBASSADOR", "ANALYST", "APPRAISER", "ARCHITECT", "ARTIST", "ASSISTANT", "ATHLETE", "ATTENDANT", "ATTORNEY", "AUCTIONEER", "AUDITOR", "BARBER", "BROKER", "BUSINESS_EXEC", "BUSINESS_OWNER", "CAREGIVER", "CARPENTER", "CASHIER", "CHEF", "CHIROPRACTOR", "CIVIL", "CLERGY", "CLERK", "COMPLIANCE", "CONSULTANT", "CONTRACTOR", "COUNSELOR", "CUSTOMER_SERVICE", "DEALER", "DEVELOPER", "DISTRIBUTOR", "DOCTOR", "DRIVER", "ENGINEER", "EXAMINER", "EXTERMINATOR", "FACTORY", "FARMER", "FINANCIAL", "FISHERMAN", "FLIGHT", "HR", "IMPEX", "INSPECTOR", "INTERN", "INVESTMENT", "INVESTOR", "IT", "JANITOR", "JEWELER", "LABORER", "LANDSCAPER", "LENDING", "MANAGER", "MECHANIC", "MILITARY", "MORTICIAN", "NURSE", "NUTRITIONIST", "OFFICE", "PHARMACIST", "PHYSICAL", "PILOT", "POLICE", "POLITICIAN", "PM", "REP", "RESEARCHER", "SAILOR", "SALES", "SCIENTIST", "SEAMSTRESS", "SECURITY", "SOCIAL", "TEACHER", "TECHNICIAN", "TELLER", "TRADESPERSON", "TRAINER", "TRANSPORTER", "UNDERWRITER", "WRITER" ] }, "companyId": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "type": { "type": "string", "enum": [ "agriculture", "mining", "utilities", "construction", "manufacturing", "wholesale", "retail", "transport", "information", "finance", "realEstate", "professional", "management", "education", "health", "art", "food", "publicSector", "waste" ] }, "broker": { "type": "boolean" }, "directorOf": { "type": "string" } }, "required": [ "status", "broker", "directorOf" ] }, "identification": { "type": "object", "properties": { "taxIdType": { "type": "string", "enum": [ "ssn", "itin", "fein", "nino", "other" ] }, "taxId": { "type": "string", "minLength": 1 }, "issuingCountry": { "type": "string", "pattern": "^[A-Z]{3}$" }, "usTaxPayer": { "type": "boolean" } }, "required": [ "taxIdType", "taxId", "issuingCountry" ] }, "disclosures": { "type": "object", "properties": { "extendedHoursAgreement": { "type": "boolean" }, "termsOfUse": { "type": "boolean" }, "customerAgreement": { "type": "boolean" }, "iraAgreement": { "type": "boolean" }, "marginAgreement": { "type": "boolean" }, "cryptoAgreements": { "type": "boolean" }, "marketDataAgreement": { "type": "boolean" }, "optionsAgreement": { "type": "boolean" }, "rule14b": { "type": "boolean" }, "finderFee": { "type": "boolean" }, "privacyPolicy": { "type": "boolean" }, "dataSharing": { "type": "boolean" }, "signedBy": { "type": "string" } }, "required": [ "extendedHoursAgreement", "termsOfUse", "customerAgreement", "iraAgreement", "marginAgreement", "cryptoAgreements", "marketDataAgreement", "optionsAgreement", "rule14b", "finderFee", "privacyPolicy", "dataSharing", "signedBy" ] }, "investorProfile": { "type": "object", "properties": { "riskTolerance": { "type": "string", "enum": [ "low", "moderate", "speculation", "high" ] }, "investmentExperience": { "type": "string", "enum": [ "none", "yrs1Less", "yrs1To2", "yrs3To5", "yrs5To10", "yrs10Plus" ] }, "investmentObjectives": { "type": "string", "enum": [ "capitalPreservation", "income", "growth", "speculation" ] }, "annualIncome": { "type": "number", "minimum": 0 }, "totalNetWorth": { "type": "number", "minimum": 0 }, "liquidNetWorth": { "type": "number", "minimum": 0 }, "dependents": { "type": "integer", "minimum": 0 }, "suitabilityEquities": { "type": "string" }, "suitabilityOptions": { "type": "string" } }, "required": [ "annualIncome", "totalNetWorth" ] }, "taxInfo": { "type": "object", "properties": { "taxTreatyWithUS": { "type": "boolean" } } }, "status": { "type": "string", "enum": [ "notStarted", "inProgress", "ready", "submitted", "completed", "failed", "pending" ] }, "canSubmit": { "type": "boolean" }, "physicalDocuments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "side": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "uploaded", "approved", "rejected" ] }, "uploadedAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" } }, "required": [ "id", "type", "status" ] } }, "accountPreference": { "type": "string" }, "selectedPortfolioId": { "type": "string" }, "financialGoal": { "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "partnerId", "emailAddress", "kycStatus", "country", "language" ], "example": { "id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "partnerId": "partner_demo_001", "emailAddress": "integration.demo@client-example.com", "kycStatus": "inReview", "country": "USA", "language": "en_US", "personalInfo": { "birthDay": 15, "birthMonth": 8, "birthYear": 1985, "citizenship": "USA", "gender": "female", "maritalStatus": "single" }, "address": { "street1": "123 Integration Way", "city": "San Francisco", "province": "CA", "postalCode": "94105", "country": "USA" }, "status": "submitted", "canSubmit": false, "physicalDocuments": [ { "id": "doc_1abc2def", "type": "PASSPORT", "side": "FRONT", "status": "uploaded", "uploadedAt": "2023-10-27T14:30:00Z" } ], "accountPreference": "selfManaged", "financialGoal": "Long-term growth" } } } } }, "400": { "description": "Missing person ID, empty update payload, or invalid body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "array", "items": {} } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, or expired partner API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Person does not belong to the authenticated partner, or partner is suspended.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Person not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "422": { "description": "Submitted category values are invalid for the broker or domain.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "502": { "description": "Broker-side document update failure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } } } }, "get": { "summary": "Get a person", "description": "Returns the current partner-scoped person plus onboarding status context when available.", "tags": [ "Person" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Internal person UUID" }, "required": true, "description": "Internal person UUID", "name": "personId", "in": "path" } ], "responses": { "200": { "description": "Person found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "partnerId": { "type": "string" }, "emailAddress": { "type": "string", "format": "email" }, "kycStatus": { "type": "string", "enum": [ "pending", "inReview", "needsMoreInfo", "approved", "rejected", "expired" ] }, "country": { "type": "string", "pattern": "^[A-Z]{3}$" }, "language": { "type": "string" }, "personalInfo": { "type": "object", "properties": { "birthDay": { "type": "integer", "minimum": 1, "maximum": 31 }, "birthMonth": { "type": "integer", "minimum": 1, "maximum": 12 }, "birthYear": { "type": "integer", "minimum": 1900 }, "citizenship": { "type": "string", "pattern": "^[A-Z]{3}$" }, "politicallyExposedNames": { "type": "string" }, "irsBackupWithholdings": { "type": "boolean" }, "gender": { "type": "string", "enum": [ "male", "female" ] }, "maritalStatus": { "type": "string", "enum": [ "single", "divorced", "married", "widowed", "partner" ] } }, "required": [ "birthDay", "birthMonth", "birthYear", "citizenship" ] }, "address": { "type": "object", "properties": { "street1": { "type": "string", "minLength": 1 }, "street2": { "type": "string" }, "city": { "type": "string", "minLength": 1 }, "province": { "type": "string", "minLength": 1 }, "postalCode": { "type": "string", "minLength": 1 }, "country": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "street1", "city", "province", "postalCode", "country" ] }, "employment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "employed", "selfEmployed", "unemployed", "retired", "student" ] }, "employerName": { "type": "string" }, "occupation": { "type": "string", "enum": [ "ACCOUNTANT", "ACTUARY", "ADJUSTER", "ADMINISTRATOR", "ADVERTISER", "AGENT", "ATC", "AMBASSADOR", "ANALYST", "APPRAISER", "ARCHITECT", "ARTIST", "ASSISTANT", "ATHLETE", "ATTENDANT", "ATTORNEY", "AUCTIONEER", "AUDITOR", "BARBER", "BROKER", "BUSINESS_EXEC", "BUSINESS_OWNER", "CAREGIVER", "CARPENTER", "CASHIER", "CHEF", "CHIROPRACTOR", "CIVIL", "CLERGY", "CLERK", "COMPLIANCE", "CONSULTANT", "CONTRACTOR", "COUNSELOR", "CUSTOMER_SERVICE", "DEALER", "DEVELOPER", "DISTRIBUTOR", "DOCTOR", "DRIVER", "ENGINEER", "EXAMINER", "EXTERMINATOR", "FACTORY", "FARMER", "FINANCIAL", "FISHERMAN", "FLIGHT", "HR", "IMPEX", "INSPECTOR", "INTERN", "INVESTMENT", "INVESTOR", "IT", "JANITOR", "JEWELER", "LABORER", "LANDSCAPER", "LENDING", "MANAGER", "MECHANIC", "MILITARY", "MORTICIAN", "NURSE", "NUTRITIONIST", "OFFICE", "PHARMACIST", "PHYSICAL", "PILOT", "POLICE", "POLITICIAN", "PM", "REP", "RESEARCHER", "SAILOR", "SALES", "SCIENTIST", "SEAMSTRESS", "SECURITY", "SOCIAL", "TEACHER", "TECHNICIAN", "TELLER", "TRADESPERSON", "TRAINER", "TRANSPORTER", "UNDERWRITER", "WRITER" ] }, "companyId": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "type": { "type": "string", "enum": [ "agriculture", "mining", "utilities", "construction", "manufacturing", "wholesale", "retail", "transport", "information", "finance", "realEstate", "professional", "management", "education", "health", "art", "food", "publicSector", "waste" ] }, "broker": { "type": "boolean" }, "directorOf": { "type": "string" } }, "required": [ "status", "broker", "directorOf" ] }, "identification": { "type": "object", "properties": { "taxIdType": { "type": "string", "enum": [ "ssn", "itin", "fein", "nino", "other" ] }, "taxId": { "type": "string", "minLength": 1 }, "issuingCountry": { "type": "string", "pattern": "^[A-Z]{3}$" }, "usTaxPayer": { "type": "boolean" } }, "required": [ "taxIdType", "taxId", "issuingCountry" ] }, "disclosures": { "type": "object", "properties": { "extendedHoursAgreement": { "type": "boolean" }, "termsOfUse": { "type": "boolean" }, "customerAgreement": { "type": "boolean" }, "iraAgreement": { "type": "boolean" }, "marginAgreement": { "type": "boolean" }, "cryptoAgreements": { "type": "boolean" }, "marketDataAgreement": { "type": "boolean" }, "optionsAgreement": { "type": "boolean" }, "rule14b": { "type": "boolean" }, "finderFee": { "type": "boolean" }, "privacyPolicy": { "type": "boolean" }, "dataSharing": { "type": "boolean" }, "signedBy": { "type": "string" } }, "required": [ "extendedHoursAgreement", "termsOfUse", "customerAgreement", "iraAgreement", "marginAgreement", "cryptoAgreements", "marketDataAgreement", "optionsAgreement", "rule14b", "finderFee", "privacyPolicy", "dataSharing", "signedBy" ] }, "investorProfile": { "type": "object", "properties": { "riskTolerance": { "type": "string", "enum": [ "low", "moderate", "speculation", "high" ] }, "investmentExperience": { "type": "string", "enum": [ "none", "yrs1Less", "yrs1To2", "yrs3To5", "yrs5To10", "yrs10Plus" ] }, "investmentObjectives": { "type": "string", "enum": [ "capitalPreservation", "income", "growth", "speculation" ] }, "annualIncome": { "type": "number", "minimum": 0 }, "totalNetWorth": { "type": "number", "minimum": 0 }, "liquidNetWorth": { "type": "number", "minimum": 0 }, "dependents": { "type": "integer", "minimum": 0 }, "suitabilityEquities": { "type": "string" }, "suitabilityOptions": { "type": "string" } }, "required": [ "annualIncome", "totalNetWorth" ] }, "taxInfo": { "type": "object", "properties": { "taxTreatyWithUS": { "type": "boolean" } } }, "status": { "type": "string", "enum": [ "notStarted", "inProgress", "ready", "submitted", "completed", "failed", "pending" ] }, "canSubmit": { "type": "boolean" }, "physicalDocuments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "side": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "uploaded", "approved", "rejected" ] }, "uploadedAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" } }, "required": [ "id", "type", "status" ] } }, "accountPreference": { "type": "string" }, "selectedPortfolioId": { "type": "string" }, "financialGoal": { "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "partnerId", "emailAddress", "kycStatus", "country", "language" ], "example": { "id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "partnerId": "partner_demo_001", "emailAddress": "integration.demo@client-example.com", "kycStatus": "inReview", "country": "USA", "language": "en_US", "personalInfo": { "birthDay": 15, "birthMonth": 8, "birthYear": 1985, "citizenship": "USA", "gender": "female", "maritalStatus": "single" }, "address": { "street1": "123 Integration Way", "city": "San Francisco", "province": "CA", "postalCode": "94105", "country": "USA" }, "status": "submitted", "canSubmit": false, "physicalDocuments": [ { "id": "doc_1abc2def", "type": "PASSPORT", "side": "FRONT", "status": "uploaded", "uploadedAt": "2023-10-27T14:30:00Z" } ], "accountPreference": "selfManaged", "financialGoal": "Long-term growth" } } } } }, "400": { "description": "Missing person ID parameter.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "array", "items": {} } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, or expired partner API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Person does not belong to the authenticated partner, or partner is suspended.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Person not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/persons/{personId}/submit": { "post": { "summary": "Submit onboarding for a person", "description": "Finalises the onboarding flow for an existing person by submitting accumulated documents to the broker. Duplicate requests with the same `Idempotency-Key` replay the original successful response instead of creating a second side effect.", "tags": [ "Person" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Internal person UUID" }, "required": true, "description": "Internal person UUID", "name": "personId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "Unique key supplied by the client to safely retry the request without duplicating side effects." }, "required": true, "description": "Unique key supplied by the client to safely retry the request without duplicating side effects.", "name": "Idempotency-Key", "in": "header" } ], "responses": { "200": { "description": "Onboarding submitted successfully.", "headers": { "Idempotency-Replayed": { "description": "Present and set to true when the response body was replayed from the idempotency cache.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "personId": { "type": "string" } }, "required": [ "personId" ], "example": { "personId": "d290f1ee-6c54-4b01-90e6-d701748f0851" } } } } }, "400": { "description": "Missing person ID or missing or empty idempotency-key header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "array", "items": {} } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, or expired partner API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Person does not belong to the authenticated partner, or partner is suspended.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Person not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "422": { "description": "Onboarding state is incomplete or broker validation rejected the submission.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "502": { "description": "Broker-side submission failure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/persons/{personId}/kyc/documents": { "post": { "summary": "Stage a KYC document", "description": "Accepts a multipart upload with a file plus document metadata, stores the binary in blob storage, and records the storage reference for the person. Duplicate requests with the same `Idempotency-Key` replay the original successful response instead of creating a second side effect.", "tags": [ "KYC Documents" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Internal person UUID" }, "required": true, "description": "Internal person UUID", "name": "personId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "Unique key supplied by the client to safely retry the request without duplicating side effects." }, "required": true, "description": "Unique key supplied by the client to safely retry the request without duplicating side effects.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "documentType": { "type": "string", "enum": [ "DRIVER_LICENSE", "PASSPORT", "NATIONAL_ID_CARD", "VOTER_ID", "WORK_PERMIT", "VISA", "RESIDENCE_PERMIT", "ACATS_IN", "ACATS_OUT", "TRANSFER_ON_DEATH", "BENEFICIARY_DOCUMENT", "BUSINESS_DOCUMENT" ], "description": "The kind of verification document being uploaded. Must match exactly one of the supported enumerations (e.g. PASSPORT, DRIVER_LICENSE)." }, "documentSide": { "type": "string", "enum": [ "FRONT", "BACK" ], "description": "Indicates which side of the physical document is shown in the file (FRONT or BACK). For passports, FRONT usually suffices." }, "file": { "type": "string", "description": "Binary document file (max 10 MB). Supported MIME types: application/pdf, image/jpeg, image/png.", "format": "binary" } }, "required": [ "documentType", "documentSide", "file" ] } } } }, "responses": { "201": { "description": "Document staged successfully.", "headers": { "Idempotency-Replayed": { "description": "Present and set to true when the response body was replayed from the idempotency cache.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "documentId": { "type": "string", "description": "Internal reference ID for the staged document." }, "status": { "type": "string", "enum": [ "pending" ], "description": "Indicates the document is stored securely but not yet submitted to the upstream broker." } }, "required": [ "documentId", "status" ], "example": { "documentId": "doc_1abc2def", "status": "pending" } } } } }, "400": { "description": "Missing file, invalid multipart fields, file too large, or missing or empty idempotency-key header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "array", "items": {} } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, or expired partner API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Partner is suspended or the person does not belong to the authenticated partner.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Person not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "422": { "description": "Person exists but cannot accept staged documents in the current onboarding state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "502": { "description": "Blob storage or upstream staging failure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/persons/{personId}/kyc/documents/upload": { "post": { "summary": "Upload staged KYC documents to broker", "description": "Downloads all staged KYC documents from blob storage and submits them to the broker. Requires the person to have an existing broker user ID. Duplicate requests with the same `Idempotency-Key` replay the original successful response instead of creating a second side effect.", "tags": [ "KYC Documents" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Internal person UUID" }, "required": true, "description": "Internal person UUID", "name": "personId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "Unique key supplied by the client to safely retry the request without duplicating side effects." }, "required": true, "description": "Unique key supplied by the client to safely retry the request without duplicating side effects.", "name": "Idempotency-Key", "in": "header" } ], "responses": { "200": { "description": "Documents uploaded successfully.", "headers": { "Idempotency-Replayed": { "description": "Present and set to true when the response body was replayed from the idempotency cache.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "uploaded": { "type": "integer", "description": "The count of previously staged documents that were successfully transmitted to the upstream broker." }, "documents": { "type": "array", "items": { "type": "object", "properties": { "documentId": { "type": "string", "description": "The internal reference for the document that was uploaded." }, "status": { "type": "string", "description": "Status reported by the broker (e.g., uploaded, under_review)." } }, "required": [ "documentId", "status" ] }, "description": "Array of results for each document included in the transmission." } }, "required": [ "uploaded", "documents" ], "example": { "uploaded": 2, "documents": [ { "documentId": "doc_1abc2def", "status": "uploaded" }, { "documentId": "doc_3ghi4jkl", "status": "uploaded" } ] } } } } }, "400": { "description": "Missing or empty Idempotency-Key header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "array", "items": {} } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, or expired partner API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Partner is suspended or the person does not belong to the authenticated partner.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Person not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "422": { "description": "Broker user not created yet or no pending documents are staged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "502": { "description": "Broker-side upload failure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/persons/{personId}/accounts": { "post": { "summary": "Open an account for a person", "description": "Creates a brokerage account for an existing person. Duplicate requests with the same `Idempotency-Key` replay the original successful response instead of creating a second side effect.", "tags": [ "Accounts" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Internal person UUID" }, "required": true, "description": "Internal person UUID", "name": "personId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "Unique key supplied by the client to safely retry the request without duplicating side effects." }, "required": true, "description": "Unique key supplied by the client to safely retry the request without duplicating side effects.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cash", "margin" ], "default": "cash" } }, "example": { "type": "cash" } } } } }, "responses": { "201": { "description": "Account opened successfully.", "headers": { "Idempotency-Replayed": { "description": "Present and set to true when the response body was replayed from the idempotency cache.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "personId": { "type": "string" }, "partnerId": { "type": "string" }, "type": { "type": "string", "enum": [ "cash", "margin" ] }, "status": { "type": "string", "enum": [ "open", "openNoNewTrades", "closed", "frozen", "suspended", "pending" ] }, "openedAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" }, "closedAt": { "type": "string", "format": "date-time", "example": "2024-01-15T09:00:00Z" } }, "required": [ "id", "personId", "partnerId", "type", "status", "openedAt" ], "example": { "id": "acc_4f7b21a9", "personId": "d290f1ee-6c54-4b01-90e6-d701748f0851", "partnerId": "partner_demo_001", "type": "cash", "status": "open", "openedAt": "2023-10-27T14:30:00Z" } } } } }, "400": { "description": "Missing person ID or missing or empty idempotency-key header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "array", "items": {} } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, or expired partner API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Partner is suspended or the person does not belong to the authenticated partner.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Person not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "422": { "description": "Account payload is invalid for the broker or person is not ready for account creation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "502": { "description": "Broker-side account creation failure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } } } }, "get": { "summary": "List a person's accounts", "description": "Lists all canonical accounts associated with the specified partner-scoped person.", "tags": [ "Accounts" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Internal person UUID" }, "required": true, "description": "Internal person UUID", "name": "personId", "in": "path" } ], "responses": { "200": { "description": "Accounts returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "personId": { "type": "string" }, "partnerId": { "type": "string" }, "type": { "type": "string", "enum": [ "cash", "margin" ] }, "status": { "type": "string", "enum": [ "open", "openNoNewTrades", "closed", "frozen", "suspended", "pending" ] }, "openedAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" }, "closedAt": { "type": "string", "format": "date-time", "example": "2024-01-15T09:00:00Z" } }, "required": [ "id", "personId", "partnerId", "type", "status", "openedAt" ], "example": { "id": "acc_4f7b21a9", "personId": "d290f1ee-6c54-4b01-90e6-d701748f0851", "partnerId": "partner_demo_001", "type": "cash", "status": "open", "openedAt": "2023-10-27T14:30:00Z" } } } }, "required": [ "accounts" ], "example": { "accounts": [ { "id": "acc_4f7b21a9", "personId": "d290f1ee-6c54-4b01-90e6-d701748f0851", "partnerId": "partner_demo_001", "type": "cash", "status": "open", "openedAt": "2023-10-27T14:30:00Z" } ] } } } } }, "400": { "description": "Missing person ID parameter.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "array", "items": {} } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, or expired partner API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Person does not belong to the authenticated partner, or partner is suspended.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Person not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/accounts/{accountId}": { "get": { "summary": "Get an account", "description": "Returns the canonical snapshot of a brokerage account by its internal account ID.", "tags": [ "Accounts" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Internal account UUID" }, "required": true, "description": "Internal account UUID", "name": "accountId", "in": "path" } ], "responses": { "200": { "description": "Account found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "personId": { "type": "string" }, "partnerId": { "type": "string" }, "type": { "type": "string", "enum": [ "cash", "margin" ] }, "status": { "type": "string", "enum": [ "open", "openNoNewTrades", "closed", "frozen", "suspended", "pending" ] }, "openedAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" }, "closedAt": { "type": "string", "format": "date-time", "example": "2024-01-15T09:00:00Z" } }, "required": [ "id", "personId", "partnerId", "type", "status", "openedAt" ], "example": { "id": "acc_4f7b21a9", "personId": "d290f1ee-6c54-4b01-90e6-d701748f0851", "partnerId": "partner_demo_001", "type": "cash", "status": "open", "openedAt": "2023-10-27T14:30:00Z" } } } } }, "400": { "description": "Missing account ID parameter.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "array", "items": {} } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, or expired partner API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Account does not belong to the authenticated partner, or partner is suspended.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Account not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/accounts/{accountId}/orders": { "post": { "summary": "Place an order", "description": "Submits a new market or limit order for the specified account. The request is subject to pre-trade risk and balance checks. Duplicate requests with the same `Idempotency-Key` replay the original successful response instead of creating a second side effect. When `type` is `limit`, clients must also provide `limitPrice`.", "tags": [ "Trading" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Internal account UUID" }, "required": true, "description": "Internal account UUID", "name": "accountId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "Unique key supplied by the client to safely retry the request without duplicating side effects." }, "required": true, "description": "Unique key supplied by the client to safely retry the request without duplicating side effects.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string", "minLength": 1, "maxLength": 10, "description": "The tradable ticker symbol to submit to the broker, e.g. AAPL." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "Order side: buy or sell." }, "type": { "type": "string", "enum": [ "market", "limit" ], "description": "Execution type. Use `market` for immediate execution at prevailing prices or `limit` to cap the acceptable execution price." }, "quantity": { "type": "number", "exclusiveMinimum": 0, "description": "Number of shares to trade. Fractional quantities may be accepted when the underlying broker and instrument support them." }, "timeInForce": { "type": "string", "enum": [ "day", "gtc", "ioc", "fok" ], "description": "How long the order should remain active at the broker." }, "limitPrice": { "type": "number", "exclusiveMinimum": 0, "description": "Required when `type` is `limit`. Represents the highest buy price or lowest sell price the client is willing to accept." } }, "required": [ "symbol", "side", "type", "quantity", "timeInForce" ], "example": { "symbol": "AAPL", "side": "buy", "type": "market", "quantity": 1.5, "timeInForce": "day" } } } } }, "responses": { "201": { "description": "Order placed successfully.", "headers": { "Idempotency-Replayed": { "description": "Present and set to true when the response body was replayed from the idempotency cache.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "symbol": { "type": "string" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "type": { "type": "string", "enum": [ "market", "limit" ] }, "quantity": { "type": "number" }, "limitPrice": { "type": "number" }, "status": { "type": "string", "enum": [ "pending", "open", "filled", "cancelled", "rejected" ], "description": "Current broker order lifecycle status. Common values include pending, open, filled, cancelled, and rejected." }, "timeInForce": { "type": "string", "enum": [ "day", "gtc", "ioc", "fok" ] }, "placedAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" }, "filledAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:05Z" }, "cancelledAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:31:00Z" } }, "required": [ "id", "accountId", "symbol", "side", "type", "quantity", "status", "timeInForce", "placedAt" ], "example": { "id": "ord_123abc456", "accountId": "a8a8166c-240e-436f-b27b-e1b9b28b6d26", "symbol": "AAPL", "side": "buy", "type": "market", "quantity": 1.5, "status": "filled", "timeInForce": "day", "placedAt": "2023-10-27T14:30:00Z", "filledAt": "2023-10-27T14:30:05Z" } } } } }, "400": { "description": "Invalid request body, pre-trade check rejected, or missing or empty idempotency-key header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "array", "items": {} } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, or expired partner API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Account does not belong to the authenticated partner, or partner is suspended.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Account not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "502": { "description": "Upstream broker failure." } } }, "get": { "summary": "List orders for an account", "tags": [ "Trading" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Internal account UUID" }, "required": true, "description": "Internal account UUID", "name": "accountId", "in": "path" } ], "responses": { "200": { "description": "Orders returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "symbol": { "type": "string" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "type": { "type": "string", "enum": [ "market", "limit" ] }, "quantity": { "type": "number" }, "limitPrice": { "type": "number" }, "status": { "type": "string", "enum": [ "pending", "open", "filled", "cancelled", "rejected" ], "description": "Current broker order lifecycle status. Common values include pending, open, filled, cancelled, and rejected." }, "timeInForce": { "type": "string", "enum": [ "day", "gtc", "ioc", "fok" ] }, "placedAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" }, "filledAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:05Z" }, "cancelledAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:31:00Z" } }, "required": [ "id", "accountId", "symbol", "side", "type", "quantity", "status", "timeInForce", "placedAt" ], "example": { "id": "ord_123abc456", "accountId": "a8a8166c-240e-436f-b27b-e1b9b28b6d26", "symbol": "AAPL", "side": "buy", "type": "market", "quantity": 1.5, "status": "filled", "timeInForce": "day", "placedAt": "2023-10-27T14:30:00Z", "filledAt": "2023-10-27T14:30:05Z" } } } }, "required": [ "orders" ], "example": { "orders": [ { "id": "ord_123abc456", "accountId": "a8a8166c-240e-436f-b27b-e1b9b28b6d26", "symbol": "AAPL", "side": "buy", "type": "market", "quantity": 1.5, "status": "filled", "timeInForce": "day", "placedAt": "2023-10-27T14:30:00Z", "filledAt": "2023-10-27T14:30:05Z" } ] } } } } }, "401": { "description": "Missing, invalid, or expired partner API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Account does not belong to the authenticated partner, or partner is suspended.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Account not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/orders/{orderId}": { "get": { "summary": "Get an order", "tags": [ "Trading" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Broker-assigned order ID" }, "required": true, "description": "Broker-assigned order ID", "name": "orderId", "in": "path" } ], "responses": { "200": { "description": "Order found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "symbol": { "type": "string" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "type": { "type": "string", "enum": [ "market", "limit" ] }, "quantity": { "type": "number" }, "limitPrice": { "type": "number" }, "status": { "type": "string", "enum": [ "pending", "open", "filled", "cancelled", "rejected" ], "description": "Current broker order lifecycle status. Common values include pending, open, filled, cancelled, and rejected." }, "timeInForce": { "type": "string", "enum": [ "day", "gtc", "ioc", "fok" ] }, "placedAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" }, "filledAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:05Z" }, "cancelledAt": { "type": "string", "format": "date-time", "example": "2023-10-27T14:31:00Z" } }, "required": [ "id", "accountId", "symbol", "side", "type", "quantity", "status", "timeInForce", "placedAt" ], "example": { "id": "ord_123abc456", "accountId": "a8a8166c-240e-436f-b27b-e1b9b28b6d26", "symbol": "AAPL", "side": "buy", "type": "market", "quantity": 1.5, "status": "filled", "timeInForce": "day", "placedAt": "2023-10-27T14:30:00Z", "filledAt": "2023-10-27T14:30:05Z" } } } } }, "401": { "description": "Missing, invalid, or expired partner API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Order does not belong to the authenticated partner, or partner is suspended.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Order not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } } } }, "delete": { "summary": "Cancel an order", "description": "Attempts to cancel a broker order that is still cancellable. Orders already filled, rejected, cancelled, or otherwise terminal may return a validation error instead of being cancelled.", "tags": [ "Trading" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Broker-assigned order ID" }, "required": true, "description": "Broker-assigned order ID", "name": "orderId", "in": "path" } ], "responses": { "204": { "description": "Order cancelled successfully." }, "400": { "description": "Order is in a terminal state and cannot be cancelled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "array", "items": {} } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, or expired partner API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Order does not belong to the authenticated partner, or partner is suspended.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Order not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "502": { "description": "Upstream broker failure." } } } }, "/v1/accounts/{accountId}/positions": { "get": { "summary": "List positions for an account", "tags": [ "Trading" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Internal account UUID" }, "required": true, "description": "Internal account UUID", "name": "accountId", "in": "path" } ], "responses": { "200": { "description": "Current positions returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "positions": { "type": "array", "items": { "type": "object", "properties": { "accountBrokerId": { "type": "string", "description": "Broker-side account identifier." }, "symbol": { "type": "string", "description": "Tradable instrument symbol, e.g. AAPL." }, "quantity": { "type": "number", "description": "Current held quantity. Fractional values may be returned when the broker supports them." }, "costBasis": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ], "description": "Aggregate acquisition cost for the position." }, "marketValue": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ], "description": "Current marked-to-market value for the position." }, "asOf": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" } }, "required": [ "accountBrokerId", "symbol", "quantity", "costBasis", "marketValue", "asOf" ], "example": { "accountBrokerId": "dw-acct-001", "symbol": "AAPL", "quantity": 3.5, "costBasis": { "amount": 525.15, "currency": "USD" }, "marketValue": { "amount": 534.8, "currency": "USD" }, "asOf": "2023-10-27T14:30:00Z" } } } }, "required": [ "positions" ], "example": { "positions": [ { "accountBrokerId": "dw-acct-001", "symbol": "AAPL", "quantity": 3.5, "costBasis": { "amount": 525.15, "currency": "USD" }, "marketValue": { "amount": 534.8, "currency": "USD" }, "asOf": "2023-10-27T14:30:00Z" } ] } } } } }, "401": { "description": "Missing, invalid, or expired partner API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Account does not belong to the authenticated partner, or partner is suspended.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Account not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "502": { "description": "Upstream broker failure." } } } }, "/v1/quotes/{symbol}": { "get": { "summary": "Get a real-time or delayed quote", "description": "Returns the latest quote snapshot available from the upstream broker or market data provider for a single symbol.", "tags": [ "Market Data" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Ticker symbol, e.g. AAPL" }, "required": true, "description": "Ticker symbol, e.g. AAPL", "name": "symbol", "in": "path" } ], "responses": { "200": { "description": "Quote returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Tradable instrument symbol, e.g. AAPL." }, "bid": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ], "description": "Best displayed bid price." }, "ask": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ], "description": "Best displayed ask price." }, "last": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "amount", "currency" ], "description": "Most recent traded price." }, "asOf": { "type": "string", "format": "date-time", "example": "2023-10-27T14:30:00Z" } }, "required": [ "symbol", "bid", "ask", "last", "asOf" ], "example": { "symbol": "AAPL", "bid": { "amount": 149.99, "currency": "USD" }, "ask": { "amount": 150.01, "currency": "USD" }, "last": { "amount": 150, "currency": "USD" }, "asOf": "2023-10-27T14:30:00Z" } } } } }, "401": { "description": "Missing, invalid, or expired partner API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Symbol not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "502": { "description": "Upstream broker failure." } } } }, "/v1/instruments": { "get": { "summary": "Search instruments by symbol", "description": "Searches for tradable instruments by ticker symbol or partial name. Matching behavior is broker-defined, so clients should treat the results as a best-effort search rather than rely on a specific fuzzy or prefix rule.", "tags": [ "Market Data" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Ticker symbol or partial instrument name to search." }, "required": true, "description": "Ticker symbol or partial instrument name to search.", "name": "symbol", "in": "query" } ], "responses": { "200": { "description": "Matching instruments returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "instruments": { "type": "array", "items": { "type": "object", "properties": { "brokerId": { "type": "string", "description": "Broker-side instrument identifier." }, "symbol": { "type": "string", "description": "Tradable symbol returned by the broker." }, "name": { "type": "string", "description": "Human-readable instrument name." }, "type": { "type": "string", "enum": [ "equity", "etf", "option", "bond" ], "description": "High-level instrument category." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code for the instrument trading currency." }, "exchange": { "type": "string", "description": "Primary listing venue when available." }, "country": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 3166-1 alpha-3 country code when the broker provides it." } }, "required": [ "brokerId", "symbol", "name", "type", "currency" ], "example": { "brokerId": "inst-aapl-us", "symbol": "AAPL", "name": "Apple Inc.", "type": "equity", "currency": "USD", "exchange": "NASDAQ", "country": "USA" } } } }, "required": [ "instruments" ], "example": { "instruments": [ { "brokerId": "inst-aapl-us", "symbol": "AAPL", "name": "Apple Inc.", "type": "equity", "currency": "USD", "exchange": "NASDAQ", "country": "USA" } ] } } } } }, "400": { "description": "symbol query param is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "array", "items": {} } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, or expired partner API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "502": { "description": "Upstream broker failure." } } } } }, "webhooks": {} }