Skip to content

Add a seller and agent

Use this optional flow to submit a seller, an agent, or both. No separate enablement is required. Existing updateOffer integrations continue working unchanged.

Use createOffer to get an address-only request ID. Then call submitOffer with the home details and people together. Do this before sending seller contact details through updateOffer.

const request = await client.createOffer({ address });
const plan = {
idempotencyKey: 'submission-001',
homeDetails: { homeBedrooms: 3 },
participants: [
{
ref: 'owner',
fullName: 'Dana Owner',
email: 'dana@example.com',
roles: ['SELLER'],
},
{
ref: 'agent',
fullName: 'Alex Agent',
email: 'alex@example.com',
roles: ['SELLER_AGENT'],
},
],
primaryParticipantRef: 'agent',
representation: {
agentRef: 'agent',
sellerRef: 'owner',
signedListingAgreement: true,
},
} satisfies SubmitOfferRequest;
await client.submitOffer(request.opendoorOfferRequestId, plan);
const progress = await client.getOfferSubmission(
request.opendoorOfferRequestId
);

Import SubmitOfferRequest from the SDK package you use. The Node client calls Opendoor. The browser client calls your backend and uses the same request and response shapes.

The browser, Node, and Ruby SDKs trim surrounding whitespace and lowercase participant emails before validation and submission. They leave your input object unchanged.

This example invites both people. Set primaryParticipantRef to either person’s reference without changing their role. An agent selling their own home is one person with both roles. Agent-only requests omit representation.sellerRef; requests without an agent omit representation. Existing agent fee rules still apply.

READY describes setup, rather than pricing or email delivery. Participant states reflect the latest setup attempt, not a live invitation tracking feed. Keep using the existing offer queries for pricing. Retry a timed-out submission with the same key and data. Use opaque participant references containing letters, numbers, underscores, or hyphens (up to 128 characters), and keep contact information out of references. Contact details and roles are immutable after submission.

The Node and Ruby clients read OfferRequest.participantSetup through GraphQL. Both submission and setup-status methods return the flat setup result shown above. A request without a submitted participant plan raises NOT_FOUND.

Connect the browser client

Implement these routes in your backend, using the server SDK and your server-held API key:

Browser routeServer call
POST /offer/submit with { offerId, ...plan }client.submitOffer(offerId, plan)
POST /offer/submission with { offerId }client.getOfferSubmission(offerId)

These are the default paths relative to the browser client’s baseURL. Override them through its endpoints option when your backend uses different paths. The repository’s Express dev server includes these handlers. Authenticate your own users and verify that they may access the requested deal before forwarding a request.

Collect the inputs

A custom partner flow can show separate homeowner and agent contact fields, and choose which person is the main contact. Everyone included receives an invitation. A main-contact selection does not establish home ownership or signing rights.

React and Vue integrations can use the framework-independent browser client for these operations. Existing onboarding components and their submission behavior remain unchanged. Keep home answers separate from participant contacts when building the new submission.

Ruby

The Ruby server SDK exposes the same operations and accepts snake_case input keys:

client.submit_offer(offer_id: request_id, data: {
idempotency_key: "submission-001",
primary_participant_ref: "owner",
participants: [{ ref: "owner", full_name: "Dana Owner", email: "dana@example.com",
roles: ["SELLER"] }]
})
client.get_offer_submission(offer_id: request_id)