openapi: 3.0.3 info: title: 'GoESCROW API Documentation' description: '' version: 1.0.0 servers: - url: 'https://partners.staging.goescrow.net' tags: - name: System description: '' - name: 'Company Management' description: 'Manage Companies' - name: 'User Management' description: 'Manage Users' - name: 'Transaction Management' description: 'Manage Transactions' - name: 'User Identification Management' description: 'Manage User Identification Documents' paths: /api/v1/healthcheck: get: summary: '' operationId: getApiV1Healthcheck description: '' parameters: [] responses: { } tags: - System security: [] /api/v1/companies: post: summary: 'Create a new company' operationId: createANewCompany description: "Creates a new company with a designated company representative. The company representative will be created as a user if they don't already exist." parameters: [] responses: 201: description: 'Company created successfully' content: application/json: schema: type: object example: data: id: comp_123 name: 'Acme Corp Pty Ltd' properties: data: type: object properties: id: type: string example: comp_123 description: '' enum: [] name: type: string example: 'Acme Corp Pty Ltd' description: '' enum: [] required: - id - name tags: - 'Company Management' requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: 'The company name' example: 'Acme Corp Pty Ltd' nullable: false abn: type: string description: 'Australian Business Number' example: '12345678901' nullable: false acn: type: string description: 'Australian Company Number' example: '123456789' nullable: false email: type: string description: 'Company email address' example: info@acmecorp.com.au nullable: false phone: type: string description: 'Company phone number in international format' example: '+61298765432' nullable: false website: type: string description: 'Company website URL' example: 'https://www.acmecorp.com.au' nullable: false type: type: string description: 'Company type/structure' example: 'Proprietary Limited' nullable: false majority_owned_by_another_australian_company: type: boolean description: 'Whether the company is majority owned by another Australian company' example: false nullable: false majority_owned_by_overseas_person_or_company: type: boolean description: 'Whether the company is majority owned by an overseas person or company' example: false nullable: false majority_owned_by_listed_australian_company: type: boolean description: 'Whether the company is majority owned by a listed Australian company' example: false nullable: false acting_as_trustee_for_a_trust: type: boolean description: 'Whether the company is acting as trustee for a trust' example: false nullable: false company_representative: type: object description: '' example: first_name: John nullable: false properties: first_name: type: string description: 'Company representative first name' example: John nullable: false last_name: type: string description: 'Company representative last name' example: Smith nullable: false email: type: string description: 'Company representative email address' example: john.smith@acmecorp.com.au nullable: false phone: type: string description: 'Company representative phone number in international format' example: '+61412345678' nullable: false birth_date: type: string description: 'Company representative date of birth in YYYY-MM-DD format' example: '1985-03-15' nullable: false required: - first_name - last_name - email - phone - birth_date required: - name - email - phone - majority_owned_by_another_australian_company - majority_owned_by_overseas_person_or_company - majority_owned_by_listed_australian_company - acting_as_trustee_for_a_trust /api/v1/users: post: summary: 'Create a new user' operationId: createANewUser description: 'Creates a new user or returns an existing user if the email already exists. The user will be automatically associated with the authenticated partner.' parameters: [] responses: 201: description: 'User created successfully' content: application/json: schema: type: object example: id: 1 reference: USR-ABC123 first_name: John last_name: Doe email: john.doe@example.com phone: '+61412345678' properties: id: type: integer example: 1 description: '' enum: [] reference: type: string example: USR-ABC123 description: '' enum: [] first_name: type: string example: John description: '' enum: [] last_name: type: string example: Doe description: '' enum: [] email: type: string example: john.doe@example.com description: '' enum: [] phone: type: string example: '+61412345678' description: '' enum: [] required: - id - reference - first_name - last_name - email - phone tags: - 'User Management' requestBody: required: true content: application/json: schema: type: object properties: first_name: type: string description: "The user's first name" example: John nullable: false last_name: type: string description: "The user's last name" example: Doe nullable: false email: type: string description: "The user's email address. Must be a valid email format." example: john.doe@example.com nullable: false phone: type: string description: "The user's phone number. Must be a valid international phone number format (e.g., +614123456789)." example: '+61412345678' nullable: false birth_date: type: string description: "The user's date of birth in YYYY-MM-DD format" example: '1990-01-15' nullable: false required: - first_name - last_name - email - phone - birth_date '/api/v1/users/{user_id}/verify-mobile': get: summary: 'Send mobile verification code' operationId: sendMobileVerificationCode description: "Sends a verification code via SMS to the user's registered phone number. The code will be valid for a limited time." parameters: [] responses: 204: description: 'Verification code sent successfully' content: application/json: schema: type: array items: type: object example: [] tags: - 'User Management' post: summary: 'Verify mobile phone' operationId: verifyMobilePhone description: "Verifies the mobile phone number using the code sent via SMS. Upon successful verification, the user's phone will be marked as verified." parameters: [] responses: 204: description: 'Phone number verified successfully' content: application/json: schema: type: array items: type: object example: [] tags: - 'User Management' requestBody: required: true content: application/json: schema: type: object properties: code: type: string description: 'The verification code received via SMS' example: '123456' nullable: false required: - code parameters: - in: path name: user_id description: 'The ID of the user.' example: 0cf9acbc-2e7c-4281-a982-f1b5c03daca2 required: true schema: type: string '/api/v1/users/{user_id}/verify-email': get: summary: 'Send email verification code' operationId: sendEmailVerificationCode description: "Sends a verification code via email to the user's registered email address. The code will be valid for a limited time." parameters: [] responses: 204: description: 'Verification code sent successfully' content: application/json: schema: type: array items: type: object example: [] tags: - 'User Management' post: summary: 'Verify email address' operationId: verifyEmailAddress description: "Verifies the email address using the code sent via email. Upon successful verification, the user's email will be marked as verified." parameters: [] responses: 204: description: 'Email address verified successfully' content: application/json: schema: type: array items: type: object example: [] tags: - 'User Management' requestBody: required: true content: application/json: schema: type: object properties: code: type: string description: 'The verification code received via email' example: '123456' nullable: false required: - code parameters: - in: path name: user_id description: 'The ID of the user.' example: 0cf9acbc-2e7c-4281-a982-f1b5c03daca2 required: true schema: type: string '/api/v1/users/{user_id}/bank-statement': get: summary: 'Generate user bank statement' operationId: generateUserBankStatement description: 'Generates and returns a PDF bank statement for the specified user. The statement includes transaction history and account details.' parameters: [] responses: 200: description: 'PDF bank statement generated successfully' content: application/json: schema: type: array items: type: object example: [] tags: - 'User Management' parameters: - in: path name: user_id description: 'The ID of the user.' example: 0cf9acbc-2e7c-4281-a982-f1b5c03daca2 required: true schema: type: string /api/v1/transactions: post: summary: 'Create transaction' operationId: createTransaction description: 'Creates a new anytime escrow transaction with disbursements. The transaction will be created with pending status and will go through verification checklists.' parameters: [] responses: 201: description: 'Transaction created successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: TXN-2024-001234 sub_type: super_disbursement status: pending funding_status: pending amount: 150000.5 details: 'Property settlement for 123 Main St' created_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 reference: type: string example: TXN-2024-001234 sub_type: type: string example: super_disbursement status: type: string example: pending funding_status: type: string example: pending amount: type: number example: 150000.5 details: type: string example: 'Property settlement for 123 Main St' created_at: type: string example: '2024-01-15T10:30:00Z' tags: - 'Transaction Management' requestBody: required: true content: application/json: schema: type: object properties: sub_type: type: string description: 'The transaction sub type (optional: omit or null for plain anytime escrow)' example: super_disbursement nullable: false user_id: type: string description: 'The ID of the user creating the transaction' example: 9d2e5c8a-1234-5678-9abc-def012345678 nullable: false company_id: type: string description: 'The ID of the agent company (required for super_disbursement)' example: 9d2e5c8a-1234-5678-9abc-def012345678 nullable: false details: type: string description: 'Transaction details and description' example: 'Dental Surgery' nullable: false amount: type: number description: 'Total transaction amount in dollars' example: 150000.5 nullable: false disbursements: type: array description: 'Array of disbursement objects' example: - autem items: type: string required: - user_id - details - amount - disbursements /api/v1/transactions/quote: post: summary: 'Get transaction quote' operationId: getTransactionQuote description: 'Calculates fees and provides a quote for a transaction without creating it. Uses the same request structure as transaction creation. This allows partners to show pricing to their customers before committing to a transaction.' parameters: [] responses: 200: description: 'Transaction quote calculated successfully' content: application/json: schema: type: object example: data: sub_type: super_disbursement amount: 150000.5 partner_fee: 750 partner_fee_percentage: 0.5 goescrow_fee: 300 goescrow_fee_percentage: 0.2 total_fees: 1050 net_amount: 149950.5 disbursements_count: 2 properties: data: type: object properties: sub_type: type: string example: super_disbursement amount: type: number example: 150000.5 partner_fee: type: integer example: 750 partner_fee_percentage: type: number example: 0.5 goescrow_fee: type: integer example: 300 goescrow_fee_percentage: type: number example: 0.2 total_fees: type: integer example: 1050 net_amount: type: number example: 149950.5 disbursements_count: type: integer example: 2 tags: - 'Transaction Management' requestBody: required: true content: application/json: schema: type: object properties: sub_type: type: string description: 'The transaction sub type (optional: omit or null for plain anytime escrow)' example: super_disbursement nullable: false user_id: type: string description: 'The ID of the user creating the transaction' example: 9d2e5c8a-1234-5678-9abc-def012345678 nullable: false company_id: type: string description: 'The ID of the agent company (required for super_disbursement)' example: 9d2e5c8a-1234-5678-9abc-def012345678 nullable: false details: type: string description: 'Transaction details and description' example: 'Dental Surgery' nullable: false amount: type: number description: 'Total transaction amount in dollars' example: 150000.5 nullable: false disbursements: type: array description: 'Array of disbursement objects' example: - autem items: type: string required: - user_id - details - amount - disbursements '/api/v1/users/{user_id}/passport': post: summary: 'Create or update user passport' operationId: createOrUpdateUserPassport description: 'Creates a new passport record for the user or updates an existing one. Only one passport per user is allowed.' parameters: [] responses: 201: description: 'Passport created/updated successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 document_number: N1234567 first_name: John last_name: Doe middle_name: Michael nationality: Australian date_of_birth: '1990-01-15' date_of_issue: '2020-01-15' date_of_expiration: '2030-01-15' place_of_birth: 'Sydney, Australia' gender: M rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: '' enum: [] document_number: type: string example: N1234567 description: '' enum: [] first_name: type: string example: John last_name: type: string example: Doe middle_name: type: string example: Michael nationality: type: string example: Australian date_of_birth: type: string example: '1990-01-15' date_of_issue: type: string example: '2020-01-15' date_of_expiration: type: string example: '2030-01-15' place_of_birth: type: string example: 'Sydney, Australia' gender: type: string example: M rapidid_verification_requested_at: type: string example: null description: '' enum: [] rapidid_verified_at: type: string example: null description: '' enum: [] rapidid_failed_at: type: string example: null description: '' enum: [] created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' required: - id - document_number - rapidid_verification_requested_at - rapidid_verified_at - rapidid_failed_at tags: - 'User Identification Management' requestBody: required: true content: application/json: schema: type: object properties: document_number: type: string description: 'Passport document number' example: N1234567 nullable: false first_name: type: string description: 'First name as shown on passport' example: John nullable: false last_name: type: string description: 'Last name as shown on passport' example: Doe nullable: false middle_name: type: string description: 'Middle name as shown on passport' example: Michael nullable: false nationality: type: string description: 'Nationality as shown on passport' example: Australian nullable: false date_of_birth: type: string description: 'Date of birth in YYYY-MM-DD format' example: '1990-01-15' nullable: false date_of_issue: type: string description: 'Date of issue in YYYY-MM-DD format' example: '2020-01-15' nullable: false date_of_expiration: type: string description: 'Date of expiration in YYYY-MM-DD format' example: '2030-01-15' nullable: false place_of_birth: type: string description: 'Place of birth as shown on passport' example: 'Sydney, Australia' nullable: false gender: type: string description: 'Gender as shown on passport (M, F, X, or BLANK)' example: M nullable: false required: - document_number - first_name - last_name - nationality - date_of_birth - date_of_issue - date_of_expiration - place_of_birth get: summary: 'Get user passport' operationId: getUserPassport description: 'Retrieves the passport information for the specified user.' parameters: [] responses: 200: description: 'Passport retrieved successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 document_number: N1234567 first_name: John last_name: Doe middle_name: Michael nationality: Australian date_of_birth: '1990-01-15' date_of_issue: '2020-01-15' date_of_expiration: '2030-01-15' place_of_birth: 'Sydney, Australia' gender: M rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 document_number: type: string example: N1234567 first_name: type: string example: John last_name: type: string example: Doe middle_name: type: string example: Michael nationality: type: string example: Australian date_of_birth: type: string example: '1990-01-15' date_of_issue: type: string example: '2020-01-15' date_of_expiration: type: string example: '2030-01-15' place_of_birth: type: string example: 'Sydney, Australia' gender: type: string example: M rapidid_verification_requested_at: type: string example: null rapidid_verified_at: type: string example: null rapidid_failed_at: type: string example: null created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' 404: description: 'Passport not found' content: application/json: schema: type: object example: error: 'Passport not found for this user.' properties: error: type: string example: 'Passport not found for this user.' tags: - 'User Identification Management' delete: summary: 'Delete user passport' operationId: deleteUserPassport description: 'Deletes the passport record for the specified user.' parameters: [] responses: 204: description: 'Passport deleted successfully' content: application/json: schema: type: array items: type: object example: [] 404: description: 'Passport not found' content: application/json: schema: type: object example: error: 'Passport not found for this user.' properties: error: type: string example: 'Passport not found for this user.' tags: - 'User Identification Management' parameters: - in: path name: user_id description: 'The user ID' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/medicare': post: summary: 'Create or update user Medicare card' operationId: createOrUpdateUserMedicareCard description: 'Creates a new Medicare card record for the user or updates an existing one. Only one Medicare card per user is allowed.' parameters: [] responses: 201: description: 'Medicare card created/updated successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 document_number: '1234567890' name_on_card: 'John Michael Doe' card_color: green individual_reference_number: '1' expiration_date: 2025-12 rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: '' enum: [] document_number: type: string example: '1234567890' description: '' enum: [] name_on_card: type: string example: 'John Michael Doe' card_color: type: string example: green description: '' enum: [] individual_reference_number: type: string example: '1' expiration_date: type: string example: 2025-12 rapidid_verification_requested_at: type: string example: null description: '' enum: [] rapidid_verified_at: type: string example: null description: '' enum: [] rapidid_failed_at: type: string example: null description: '' enum: [] created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' required: - id - document_number - card_color - rapidid_verification_requested_at - rapidid_verified_at - rapidid_failed_at tags: - 'User Identification Management' requestBody: required: true content: application/json: schema: type: object properties: document_number: type: string description: 'Medicare card number (10 digits)' example: '1234567890' nullable: false name_on_card: type: string description: 'Name as shown on Medicare card' example: 'John Michael Doe' nullable: false card_color: type: string description: 'Medicare card color (green, blue, or yellow)' example: green nullable: false individual_reference_number: type: string description: 'Individual reference number (1 digit)' example: '1' nullable: false expiration_date: type: string description: 'Expiration date in YYYY-MM format' example: 2025-12 nullable: false required: - document_number - card_color - individual_reference_number - expiration_date get: summary: 'Get user Medicare card' operationId: getUserMedicareCard description: 'Retrieves the Medicare card information for the specified user.' parameters: [] responses: 200: description: 'Medicare card retrieved successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 document_number: '1234567890' name_on_card: 'John Michael Doe' card_color: green individual_reference_number: '1' expiration_date: 2025-12 rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 document_number: type: string example: '1234567890' name_on_card: type: string example: 'John Michael Doe' card_color: type: string example: green individual_reference_number: type: string example: '1' expiration_date: type: string example: 2025-12 rapidid_verification_requested_at: type: string example: null rapidid_verified_at: type: string example: null rapidid_failed_at: type: string example: null created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' 404: description: 'Medicare card not found' content: application/json: schema: type: object example: error: 'Medicare card not found for this user.' properties: error: type: string example: 'Medicare card not found for this user.' tags: - 'User Identification Management' delete: summary: 'Delete user Medicare card' operationId: deleteUserMedicareCard description: 'Deletes the Medicare card record for the specified user.' parameters: [] responses: 204: description: 'Medicare card deleted successfully' content: application/json: schema: type: array items: type: object example: [] 404: description: 'Medicare card not found' content: application/json: schema: type: object example: error: 'Medicare card not found for this user.' properties: error: type: string example: 'Medicare card not found for this user.' tags: - 'User Identification Management' parameters: - in: path name: user_id description: 'The user ID' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/driver-license': post: summary: 'Create or update user driver license' operationId: createOrUpdateUserDriverLicense description: 'Creates a new driver license record for the user or updates an existing one. Only one driver license per user is allowed.' parameters: [] responses: 201: description: 'Driver license created/updated successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 state_issued: NSW license_number: '12345678' card_number: '1234567890' expiration_date: '2030-01-15' first_name: John last_name: Doe middle_name: Michael date_of_birth: '1990-01-15' rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: '' enum: [] state_issued: type: string example: NSW description: '' enum: [] license_number: type: string example: '12345678' description: '' enum: [] card_number: type: string example: '1234567890' expiration_date: type: string example: '2030-01-15' first_name: type: string example: John last_name: type: string example: Doe middle_name: type: string example: Michael date_of_birth: type: string example: '1990-01-15' rapidid_verification_requested_at: type: string example: null description: '' enum: [] rapidid_verified_at: type: string example: null description: '' enum: [] rapidid_failed_at: type: string example: null description: '' enum: [] created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' required: - id - state_issued - license_number - rapidid_verification_requested_at - rapidid_verified_at - rapidid_failed_at tags: - 'User Identification Management' requestBody: required: true content: application/json: schema: type: object properties: state_issued: type: string description: 'State or territory that issued the license (NSW, VIC, QLD, SA, WA, TAS, NT, ACT)' example: NSW nullable: false license_number: type: string description: 'Driver license number' example: '12345678' nullable: false card_number: type: string description: 'Driver license card number' example: '1234567890' nullable: false expiration_date: type: string description: 'Expiration date in YYYY-MM-DD format' example: '2030-01-15' nullable: false first_name: type: string description: 'First name as shown on license' example: John nullable: false last_name: type: string description: 'Last name as shown on license' example: Doe nullable: false middle_name: type: string description: 'Middle name as shown on license' example: Michael nullable: false date_of_birth: type: string description: 'Date of birth in YYYY-MM-DD format' example: '1990-01-15' nullable: false required: - state_issued - license_number - card_number - expiration_date - first_name - last_name - date_of_birth get: summary: 'Get user driver license' operationId: getUserDriverLicense description: 'Retrieves the driver license information for the specified user.' parameters: [] responses: 200: description: 'Driver license retrieved successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 state_issued: NSW license_number: '12345678' card_number: '1234567890' expiration_date: '2030-01-15' first_name: John last_name: Doe middle_name: Michael date_of_birth: '1990-01-15' rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 state_issued: type: string example: NSW license_number: type: string example: '12345678' card_number: type: string example: '1234567890' expiration_date: type: string example: '2030-01-15' first_name: type: string example: John last_name: type: string example: Doe middle_name: type: string example: Michael date_of_birth: type: string example: '1990-01-15' rapidid_verification_requested_at: type: string example: null rapidid_verified_at: type: string example: null rapidid_failed_at: type: string example: null created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' 404: description: 'Driver license not found' content: application/json: schema: type: object example: error: 'Driver license not found for this user.' properties: error: type: string example: 'Driver license not found for this user.' tags: - 'User Identification Management' delete: summary: 'Delete user driver license' operationId: deleteUserDriverLicense description: 'Deletes the driver license record for the specified user.' parameters: [] responses: 204: description: 'Driver license deleted successfully' content: application/json: schema: type: array items: type: object example: [] 404: description: 'Driver license not found' content: application/json: schema: type: object example: error: 'Driver license not found for this user.' properties: error: type: string example: 'Driver license not found for this user.' tags: - 'User Identification Management' parameters: - in: path name: user_id description: 'The user ID' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string