Onboarding

​

Suggested Flow

1. Create onboarding session, or retreive details of a previously created session
2. Capture or update applicant contact details.
3. Capture applicant profile and addresses.
4. Review pending requirements.
5. Submit for internal review.
6. Register webhook for party.ready.
7. Retrieve resulting party and party addresses.

---

​

Session

​

POST /onboarding-sessions

• OpenAPI path: /public/onboarding-sessions
• operationId: createOnboardingSession
• Objective: Create a new onboarding session and return the created session payload.
• Request payload: Required JSON body.
  • Example:
    {
      "type": "business",
      "country_of_incorporation": "US",
      "entry_channel": "partner_portal",
      "locale": "en-US"
    }
    
• Possible responses:
  • 201 Onboarding session created
    • Example:
      {
        "session_id": "11111111-1111-4111-8111-111111111111",
        "type": "business",
        "country_of_incorporation": "US",
        "entry_channel": "partner_portal",
        "locale": "en-US",
        "status": "IN_PROGRESS",
        "current_step": "PHONE_VERIFICATION",
        "created_at": "2026-05-01T00:00:00.000Z",
        "updated_at": "2026-05-01T00:00:00.000Z"
      }
      
  • 400 Validation or malformed request
    • Example:
      { "error": "country_of_incorporation and locale are required" }
      
  • 500 Database error while creating session
    • Example:
      { "error": "DB error", "detail": "Failed to create onboarding session" }
      
• Proper use example:
  curl -X POST "https://api.rhino-asset.com/public/onboarding-sessions" \
    -H "Content-Type: application/json" \
    -d '{"type":"business","country_of_incorporation":"US","entry_channel":"partner_portal","locale":"en-US"}'
  

​

GET /onboarding-sessions/{sessionId}

• OpenAPI path: /public/onboarding-sessions/{sessionId}
• operationId: getOnboardingSession
• Objective: Retrieve the current onboarding session state for a given session identifier.
• Request payload: None.
• Possible responses:
  • 200 Successful response
    • Example:
      { "ok": true }
      
  • 501 Not implemented (placeholder handler)
    • Example:
      { "error": "Not implemented", "operation_id": "getOnboardingSession" }
      
• Proper use example:
  curl -X GET "https://api.rhino-asset.com/public/onboarding-sessions/{sessionId}"
  

---

​

Onboarding Addresses (Session Scope)

​

GET /onboarding-sessions/{sessionId}/addresses

• OpenAPI path: /public/onboarding-sessions/{sessionId}/addresses
• operationId: listOnboardingAddresses
• Objective: List addresses captured while the user is still in the onboarding session flow.
• Request payload: None.
• Possible responses:
  • 200 Successful response
    • Example:
      { "ok": true }
      
  • 501 Not implemented (placeholder handler)
    • Example:
      { "error": "Not implemented", "operation_id": "listOnboardingAddresses" }
      
• Proper use example:
  curl -X GET "https://api.rhino-asset.com/public/onboarding-sessions/{sessionId}/addresses"
  

​

POST /onboarding-sessions/{sessionId}/addresses

• OpenAPI path: /public/onboarding-sessions/{sessionId}/addresses
• operationId: createOnboardingAddress
• Objective: Add a new address record associated with the onboarding session before party finalization.
• Request payload: Required JSON body.
  • Example:
    { "example_field": "value" }
    
• Possible responses:
  • 201 Successful response
    • Example:
      { "ok": true }
      
  • 501 Not implemented (placeholder handler)
    • Example:
      { "error": "Not implemented", "operation_id": "createOnboardingAddress" }
      
• Proper use example:
  curl -X POST "https://api.rhino-asset.com/public/onboarding-sessions/{sessionId}/addresses" \
    -H "Content-Type: application/json" \
    -d '{"example_field":"value"}'
  

​

PATCH /onboarding-sessions/{sessionId}/addresses/{addressId}

• OpenAPI path: /public/onboarding-sessions/{sessionId}/addresses/{addressId}
• operationId: updateOnboardingAddress
• Objective: Update an existing onboarding-session address (partial update).
• Request payload: Required JSON body.
  • Example:
    { "example_field": "value" }
    
• Possible responses:
  • 200 Successful response
    • Example:
      { "ok": true }
      
  • 501 Not implemented (placeholder handler)
    • Example:
      { "error": "Not implemented", "operation_id": "updateOnboardingAddress" }
      
• Proper use example:
  curl -X PATCH "https://api.rhino-asset.com/public/onboarding-sessions/{sessionId}/addresses/{addressId}" \
    -H "Content-Type: application/json" \
    -d '{"example_field":"value"}'
  

---

​

Applicant Profile

​

PUT /onboarding-sessions/{sessionId}/applicant-profile

• OpenAPI path: /public/onboarding-sessions/{sessionId}/applicant-profile
• operationId: upsertApplicantProfile
• Objective: Create or replace the applicant profile details collected during onboarding.
• Request payload: Required JSON body.
  • Example:
    { "example_field": "value" }
    
• Possible responses:
  • 200 Successful response
    • Example:
      { "ok": true }
      
  • 501 Not implemented (placeholder handler)
    • Example:
      { "error": "Not implemented", "operation_id": "upsertApplicantProfile" }
      
• Proper use example:
  curl -X PUT "https://api.rhino-asset.com/public/onboarding-sessions/{sessionId}/applicant-profile" \
    -H "Content-Type: application/json" \
    -d '{"example_field":"value"}'
  

---

​

Contact Verification

​

POST /onboarding-sessions/{sessionId}/contact/email

• OpenAPI path: /public/onboarding-sessions/{sessionId}/contact/email
• operationId: submitOnboardingEmail
• Objective: Submit or update the applicant email address as part of contact verification during onboarding.
• Request payload: Required JSON body.
  • Example:
    { "example_field": "value" }
    
• Possible responses:
  • 201 Successful response
    • Example:
      { "ok": true }
      
  • 501 Not implemented (placeholder handler)
    • Example:
      { "error": "Not implemented", "operation_id": "submitOnboardingEmail" }
      
• Proper use example:
  curl -X POST "https://api.rhino-asset.com/public/onboarding-sessions/{sessionId}/contact/email" \
    -H "Content-Type: application/json" \
    -d '{"example_field":"value"}'
  

​

POST /onboarding-sessions/{sessionId}/contact/email/retry

• OpenAPI path: /public/onboarding-sessions/{sessionId}/contact/email/retry
• operationId: retryOnboardingEmailVerification
• Objective: Request a new email verification code or retry the email verification step.
• Request payload: Required JSON body.
  • Example:
    { "example_field": "value" }
    
• Possible responses:
  • 201 Successful response
    • Example:
      { "ok": true }
      
  • 501 Not implemented (placeholder handler)
    • Example:
      { "error": "Not implemented", "operation_id": "retryOnboardingEmailVerification" }
      
• Proper use example:
  curl -X POST "https://api.rhino-asset.com/public/onboarding-sessions/{sessionId}/contact/email/retry" \
    -H "Content-Type: application/json" \
    -d '{"example_field":"value"}'
  

​

POST /onboarding-sessions/{sessionId}/contact/phone

• OpenAPI path: /public/onboarding-sessions/{sessionId}/contact/phone
• operationId: submitOnboardingPhone
• Objective: Submit or update the applicant phone number for SMS or call verification during onboarding.
• Request payload: Required JSON body.
  • Example:
    { "example_field": "value" }
    
• Possible responses:
  • 201 Successful response
    • Example:
      { "ok": true }
      
  • 501 Not implemented (placeholder handler)
    • Example:
      { "error": "Not implemented", "operation_id": "submitOnboardingPhone" }
      
• Proper use example:
  curl -X POST "https://api.rhino-asset.com/public/onboarding-sessions/{sessionId}/contact/phone" \
    -H "Content-Type: application/json" \
    -d '{"example_field":"value"}'
  

​

POST /onboarding-sessions/{sessionId}/contact/phone/retry

• OpenAPI path: /public/onboarding-sessions/{sessionId}/contact/phone/retry
• operationId: retryOnboardingPhoneVerification
• Objective: Request a new phone verification code or retry the phone verification step.
• Request payload: Required JSON body.
  • Example:
    { "example_field": "value" }
    
• Possible responses:
  • 201 Successful response
    • Example:
      { "ok": true }
      
  • 501 Not implemented (placeholder handler)
    • Example:
      { "error": "Not implemented", "operation_id": "retryOnboardingPhoneVerification" }
      
• Proper use example:
  curl -X POST "https://api.rhino-asset.com/public/onboarding-sessions/{sessionId}/contact/phone/retry" \
    -H "Content-Type: application/json" \
    -d '{"example_field":"value"}'
  

---

​

Requirements and Submission

​

GET /onboarding-sessions/{sessionId}/requirements

• OpenAPI path: /public/onboarding-sessions/{sessionId}/requirements
• operationId: listPendingOnboardingRequirements
• Objective: List outstanding onboarding requirements or checklist items the applicant must satisfy.
• Request payload: None.
• Possible responses:
  • 200 Successful response
    • Example:
      { "ok": true }
      
  • 501 Not implemented (placeholder handler)
    • Example:
      { "error": "Not implemented", "operation_id": "listPendingOnboardingRequirements" }
      
• Proper use example:
  curl -X GET "https://api.rhino-asset.com/public/onboarding-sessions/{sessionId}/requirements"
  

​

POST /onboarding-sessions/{sessionId}/submit

• OpenAPI path: /public/onboarding-sessions/{sessionId}/submit
• operationId: submitOnboardingForReview
• Objective: Submit the completed onboarding package for internal review or underwriting handoff.
• Request payload: Required JSON body.
  • Example:
    { "example_field": "value" }
    
• Possible responses:
  • 201 Successful response
    • Example:
      { "ok": true }
      
  • 501 Not implemented (placeholder handler)
    • Example:
      { "error": "Not implemented", "operation_id": "submitOnboardingForReview" }
      
• Proper use example:
  curl -X POST "https://api.rhino-asset.com/public/onboarding-sessions/{sessionId}/submit" \
    -H "Content-Type: application/json" \
    -d '{"example_field":"value"}'
  

---

​

Party Resolution and Webhook Registration

​

GET /onboarding-sessions/{sessionId}/party

• OpenAPI path: /public/onboarding-sessions/{sessionId}/party
• operationId: getPartyBySessionId
• Objective: Resolve and return the party record linked to the onboarding session, if one exists. After approval, partners may also receive the same payload via the party.ready outbound webhook.
• Request payload: None.
• Possible responses:
  • 200 Successful response
    • Example:
      { "ok": true }
      
  • 501 Not implemented (placeholder handler)
    • Example:
      { "error": "Not implemented", "operation_id": "getPartyBySessionId" }
      
• Proper use example:
  curl -X GET "https://api.rhino-asset.com/public/onboarding-sessions/{sessionId}/party"
  

​

PUT /onboarding-sessions/{sessionId}/webhook

• OpenAPI path: /public/onboarding-sessions/{sessionId}/webhook
• operationId: registerOnboardingSessionWebhook
• Objective: Register or update the HTTPS URL (and optional signing secret) where Rhino POSTs a party.ready event when internal onboarding is approved with a party_id.
• Request payload: Required JSON body.
  • Example:
    {
      "webhook_url": "example_webhook_url",
      "webhook_secret": "example_webhook_secret"
    }
    
• Possible responses:
  • 200 Successful response
    • Example:
      { "result": "response" }
      
  • 400 Validation or request format error
    • Example:
      { "error": "Invalid path" }
      
  • 500 Internal server error
    • Example:
      { "error": "Server misconfiguration" }
      
• Proper use example:
  curl -X PUT "https://api.rhino-asset.com/public/onboarding-sessions/{sessionId}/webhook" \
    -H "Content-Type: application/json" \
    -d '{"webhook_url":"example_webhook_url","webhook_secret":"example_webhook_secret"}'
  

---

​

Party Endpoints Used After Onboarding

​

GET /parties/{partyId}

• OpenAPI path: /public/parties/{partyId}
• operationId: getParty
• Objective: Fetch a party profile and core attributes for a known party identifier.
• Request payload: None.
• Possible responses:
  • 200 Successful response
    • Example:
      { "ok": true }
      
  • 501 Not implemented (placeholder handler)
    • Example:
      { "error": "Not implemented", "operation_id": "getParty" }
      
• Proper use example:
  curl -X GET "https://api.rhino-asset.com/public/parties/{partyId}"
  

​

GET /parties/{partyId}/addresses

• OpenAPI path: /public/parties/{partyId}/addresses
• operationId: listPartyAddresses
• Objective: List all addresses on file for the party after onboarding has produced a party record.
• Request payload: None.
• Possible responses:
  • 200 Successful response
    • Example:
      { "ok": true }
      
  • 501 Not implemented (placeholder handler)
    • Example:
      { "error": "Not implemented", "operation_id": "listPartyAddresses" }
      
• Proper use example:
  curl -X GET "https://api.rhino-asset.com/public/parties/{partyId}/addresses"
  

​

POST /parties/{partyId}/addresses

• OpenAPI path: /public/parties/{partyId}/addresses
• operationId: createPartyAddress
• Objective: Add a new address to the party’s permanent address book post-onboarding.
• Request payload: Required JSON body.
  • Example:
    { "example_field": "value" }
    
• Possible responses:
  • 201 Successful response
    • Example:
      { "ok": true }
      
  • 501 Not implemented (placeholder handler)
    • Example:
      { "error": "Not implemented", "operation_id": "createPartyAddress" }
      
• Proper use example:
  curl -X POST "https://api.rhino-asset.com/public/parties/{partyId}/addresses" \
    -H "Content-Type: application/json" \
    -d '{"example_field":"value"}'
  

​

PATCH /parties/{partyId}/addresses/{addressId}

• OpenAPI path: /public/parties/{partyId}/addresses/{addressId}
• operationId: updatePartyAddress
• Objective: Update an existing party address (partial update).
• Request payload: Required JSON body.
  • Example:
    { "example_field": "value" }
    
• Possible responses:
  • 200 Successful response
    • Example:
      { "ok": true }
      
  • 501 Not implemented (placeholder handler)
    • Example:
      { "error": "Not implemented", "operation_id": "updatePartyAddress" }
      
• Proper use example:
  curl -X PATCH "https://api.rhino-asset.com/public/parties/{partyId}/addresses/{addressId}" \
    -H "Content-Type: application/json" \
    -d '{"example_field":"value"}'