Skip to main content

CreateBrokerageFirmResult

The successful result of creating a brokerage firm

type CreateBrokerageFirmResult {
  firm: BrokerageFirm!
  firmAdminUid: ID
  matchedBy: BrokerageFirmMatchedBy
  organizationAssignments: [OrganizationAssignmentResult!]
  status: CreateBrokerageFirmStatus!
}

Fields​

CreateBrokerageFirmResult.firm ● BrokerageFirm! non-null object​

The brokerage firm, whether newly created or already present in the shared registry

CreateBrokerageFirmResult.firmAdminUid ● ID scalar​

The First Dollar user ID of the newly created firm administrator. Null when no administrator was provisioned, which is the case for ALREADY_EXISTED.

CreateBrokerageFirmResult.matchedBy ● BrokerageFirmMatchedBy enum​

How an existing firm was found. Set only when status is ALREADY_EXISTED, and null for CREATED.

NAME means the request had no EIN and its normalized name matched this firm. Nothing was attached: organizationAssignments is null even when organizationUlids was supplied. Confirm the match by calling assignOrganizationsToFirm with firm.id. Do not re-drive a NAME result automatically; confirming that it is the right firm is a decision for a person.

CreateBrokerageFirmResult.organizationAssignments ● [OrganizationAssignmentResult!] list object​

One element per organization supplied in organizationUlids, in the order they were submitted.

Absent when organizationUlids was absent or empty. Also absent — with a non-empty organizationUlids — in two cases that must be handled differently:

  • matchedBy: NAME: nothing was attached, because a firm matched by name is not assumed to be the right one. Do not re-drive this automatically. A person confirms the match, then attaches the organizations with assignOrganizationsToFirm.
  • CREATED or matchedBy: EIN: the firm was returned successfully but the assignment could not be completed afterwards; the firm and its administrator are intact, and the fix is to call assignOrganizationsToFirm, which is idempotent. Only this case is safe to re-drive.

Expect every element to be CREATED or ALREADY_ASSIGNED: identifiers are validated before the firm is created, so a request that reaches this point had every one of them resolve. Treat that as a strong expectation rather than a guarantee — scope is resolved twice on this path, and an organization that leaves your scope between the two resolutions comes back FAILED. Read status per element rather than assuming the array is failure-free, and recover any FAILED element with assignOrganizationsToFirm, which is idempotent.

CreateBrokerageFirmResult.status ● CreateBrokerageFirmStatus! non-null enum​

Which outcome occurred. Distinguishes a firm and administrator that were newly provisioned from an existing firm that was returned unchanged.

Implemented By​

CreateBrokerageFirmResponse union