> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.helpyousponsor.com/llms.txt > Use this file to discover all available pages before exploring further. # Verify and apply a staged relationship decision > Requires a saved pending relationship decision and a completed same-connection dry_run started after staging that includes relationship objects. The matching inbound preview event must prove the exact source relationship payload and both donor identities. Rechecks pending fingerprint, mappings and available candidates under lock before applying. keep_separate may create/adopt a forward/reverse relationship pair; choose_relationship links the selected available pair. No provider write or donor merge occurs. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings. ## OpenAPI ````yaml post /integrations/hub/conflicts/{conflict_id}/verify-relationship-identity openapi: 3.0.0 info: title: Gratona API description: >- REST API for the Gratona fundraising platform, including donor, donation, sponsorship, program, event, and integration workflows. Endpoints are organized by tag. Most endpoints require either a Passport bearer token or an issued API key — see the Security Schemes section. contact: name: Gratona Engineering url: https://gratona.com email: devs@gratona.com version: 1.0.0 servers: - url: https://api.gratona.com/v1 description: Server Version 1.0.0 security: [] tags: - name: Auth description: >- Login, signup, logout, password reset, and email verification for admin users and donors. - name: Donors description: >- Donor records: CRUD, profile fields, household linkage, search, filters, merge, and duplicate detection. - name: Donations description: >- Individual donation records, recurring commitments, soft credits, refunds, designations, and exports. - name: Sponsorships description: >- Donor-to-entity commitment relationships, lifecycle transitions, and commitment-specific filters. - name: Entities description: >- Recipient records (children, families, projects, animals, etc.), their status, and entity-level fields. - name: Programs description: >- Program / campaign configuration: hierarchy, settings, and program-level metadata. - name: Forms description: >- Custom form builder (HysForm), form fields, standardized donor fields, and field migrations. - name: Trips description: >- Mission-trip management: trips, participants, budgets, tasks, e-signatures, fundraising milestones, and background checks. - name: Communications description: >- Email templates, SMS, newsletters, donor email manager, and per-donor notes. - name: Payments description: >- Payment-gateway management (Stripe, PayPal, Flutterwave, QuickBooks). Excludes inbound webhooks — see the Webhooks tag. - name: Reports description: Dashboards, analytics, scheduled reports, and exports. - name: Admin description: >- Client-account administration: users, groups/permissions, settings, integrations, and account lifecycle. - name: Donor Portal description: >- Endpoints consumed by the donor-facing portal (donor login, dashboard, donation history, messages). - name: Recipient Portal description: Endpoints consumed by the recipient-facing portal. - name: Public description: >- Unauthenticated public endpoints: donor signup, public trip pages, peer-to-peer campaigns, public checkout. - name: Webhooks description: >- Inbound webhooks from third parties (Stripe, PayPal, Flutterwave, Checkr, DropboxSign). Annotated minimally for reference; payload shapes are owned by the upstream provider. - name: Events description: >- Event setup, invitations, registration, ticketing, attendance and event reporting. - name: Journeys description: >- Journey graphs, activation, enrollment, message templates and event follow-up automations. - name: Tasks description: Workspace tasks, assignments, saved task views and record collaboration. - name: Fundraising description: >- Fundraising portfolios, stewardship plans, giving anniversaries and personal donor follow-up. - name: Impact Stories description: Story intake, review, assets, consent and publication workflows. - name: Integrations description: Workspace integration connections, mappings, synchronization and recovery. - name: Email Calendar description: Connected email/calendar accounts and donor interactions. - name: Spaces description: Workspace Spaces and collaborative Pages. - name: Library description: Workspace documents, source connections, files and analysis. - name: Intelligence description: Donor intelligence and Tali workspace workflows. - name: Automation description: >- V3 automation primitive discovery, input validation, invocation and Zapier contracts. - name: Schema description: V3 model, enum, capability and scope discovery. - name: Zapier description: Zapier automation connections, polling feeds and actions. - name: Files description: Files - name: Client description: Client - name: Payment Gateways description: Payment Gateways - name: Email Settings description: Email Settings - name: Admin Dashboard description: Admin Dashboard - name: Recipients description: Recipients - name: Historical Archived Updates description: Historical Archived Updates - name: Team & access description: Team & access - name: Settings description: Settings - name: Notifications description: Notifications - name: Participation description: Participation - name: Users description: Users - name: Wrapped description: Wrapped - name: Donor SignUp description: Donor SignUp - name: Frontend description: Frontend - name: User description: User - name: Workspace description: Workspace paths: /integrations/hub/conflicts/{conflict_id}/verify-relationship-identity: post: tags: - Integrations summary: Verify and apply a staged relationship decision description: >- Requires a saved pending relationship decision and a completed same-connection dry_run started after staging that includes relationship objects. The matching inbound preview event must prove the exact source relationship payload and both donor identities. Rechecks pending fingerprint, mappings and available candidates under lock before applying. keep_separate may create/adopt a forward/reverse relationship pair; choose_relationship links the selected available pair. No provider write or donor merge occurs. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings. operationId: integrationHubVerifyRelationshipIdentityConflict parameters: - name: conflict_id in: path description: Conflict id in the current organization. required: true schema: type: integer example: 42 requestBody: description: Validated request fields for this operation. required: true content: application/json: schema: required: - sync_run_id properties: sync_run_id: description: 'Sync run id. Validation: required, integer, min:1.' type: integer minimum: 1 example: 1 type: object responses: '200': description: Operation result. content: application/json: schema: properties: status: type: string example: success data: $ref: '#/components/schemas/IntegrationHubConflict' message: description: >- Operation receipt; inspect returned conflict status and resolution details. type: string example: Example nullable: false type: object '401': description: Authentication is required. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' '403': description: >- The authenticated user lacks access to this workflow or its related records. '404': description: >- Feature, connection, conflict, review run or organization-owned record is unavailable. content: application/json: schema: $ref: '#/components/schemas/NotFoundResponse' '422': description: >- Request, linked-connection, stale proof, mapping/candidate or specialized-decision validation failed. content: application/json: schema: $ref: '#/components/schemas/RequestRejection' security: - bearerAuth: [] - apiKeyAuth: [] components: schemas: IntegrationHubConflict: description: >- Conflict snapshots and optional domain-specific relationship identity/recurring schedule review details. Specialized resolution contracts are documented on their operations. properties: id: description: Count. type: integer example: 2 provider_key: description: Serialized workflow value. type: string example: Example nullable: true conflict_type: description: Serialized workflow value. type: string example: Example nullable: true status: description: Serialized workflow value. type: string example: Example nullable: true hys_object_type: description: Serialized workflow value. type: string example: Example nullable: true hys_object_id: description: Identifier in the current organization. type: integer example: 42 nullable: true provider_object_type: description: Serialized workflow value. type: string example: Example nullable: true provider_object_id: description: Identifier in the current organization. type: integer example: 42 nullable: true conflicted_fields_json: description: Provider-specific stored JSON. oneOf: - type: object additionalProperties: {} - type: array items: {} - type: string enum: - null nullable: true hys_snapshot_json: description: Provider-specific stored JSON. oneOf: - type: object additionalProperties: {} - type: array items: {} - type: string enum: - null nullable: true provider_snapshot_json: description: Provider-specific stored JSON. oneOf: - type: object additionalProperties: {} - type: array items: {} - type: string enum: - null nullable: true detected_at: description: Timestamp. type: string format: date-time example: '2026-10-20T12:00:00Z' nullable: true resolved_at: description: Timestamp. type: string format: date-time example: '2026-10-20T12:00:00Z' nullable: true resolved_by: description: Identifier in the current organization. type: integer example: 42 nullable: true resolution_json: description: Provider-specific stored JSON. oneOf: - type: object additionalProperties: {} - type: array items: {} - type: string enum: - null nullable: true relationship_identity: $ref: '#/components/schemas/IntegrationHubConflictRelationship' recurring_schedule: $ref: '#/components/schemas/IntegrationHubConflictRecurring' type: object UnauthorizedResponse: title: UnauthorizedResponse description: >- Returned with HTTP 401 when the request lacks a valid Passport bearer token, a valid `X-HYS-API-Key`, or a valid session. The body is the simple `{message, status}` envelope emitted by `AuthenticateApiOrKey`. required: - message - status properties: message: description: >- Always the literal string `Unauthorized` from the `auth.api_or_key` middleware. Login endpoints return `Invalid Credentials` instead. type: string example: Unauthorized status: type: string example: error type: object NotFoundResponse: title: NotFoundResponse description: >- Returned with HTTP 404 when a resource lookup misses (typically because the id doesn't exist OR is scoped to a different `client_id`). Note: many endpoints intentionally collapse 'not found' and 'forbidden' into a single 404 to avoid leaking which records exist in another tenant. required: - message properties: message: description: >- Human-readable message. Often a more specific string like `Donor not found` or `Trip not found`. type: string example: Not Found status: type: string example: error type: object RequestRejection: description: >- Request or workflow rejection. Framework field-validation failures contain errors; semantic rejections may contain message without errors; legacy/provider failures may use error and error_code. The operation description identifies the rejected condition. Domain responses may add current revision, limits or other conflict context. anyOf: - $ref: '#/components/schemas/ValidationErrorResponse' - $ref: '#/components/schemas/ErrorResponse' - required: - error properties: error: description: Legacy or provider-facing error message. type: string example: The request could not be completed. error_code: description: Stable domain error code, when provided. type: string example: WORKFLOW_UNAVAILABLE type: object IntegrationHubConflictRelationship: description: >- Relationship collision review and conditional guards. Saving a decision leaves the conflict open with pending_resolution until a later exact verified preview applies it. properties: kind: description: >- Exact specialized relationship identity and recurring schedule conflict review projections. type: string enum: - relationship_identity collision_reason: description: Display value. type: string example: Example nullable: true source: properties: provider_object_type: description: Display value. type: string example: Example nullable: true provider_object_id: description: Display value. type: string example: Example nullable: true source_provider_id: description: Display value. type: string example: Example nullable: true related_provider_id: description: Display value. type: string example: Example nullable: true source_name: description: Display value. type: string example: Example nullable: true related_name: description: Display value. type: string example: Example nullable: true relationship_type: description: Display value. type: string example: Example nullable: true reverse_relationship_type: description: Display value. type: string example: Example nullable: true type: object current_mapping: properties: id: description: Organization-owned record identifier. type: integer example: 42 nullable: false hys_relationship_id: description: Organization-owned record identifier. type: integer example: 42 nullable: false type: object nullable: true can_keep_separate: type: boolean example: true keep_separate_will_create: type: boolean example: true can_treat_as_same_or_reverse: type: boolean example: true expected_object_mapping_id: description: Organization-owned record identifier. type: integer example: 42 nullable: true stale_mapping_token: description: Current tombstoned-claim guard, or null. type: string maxLength: 64 minLength: 64 nullable: true pending_resolution: properties: decision: description: Display value. type: string example: Example nullable: true target_hys_object_id: description: Organization-owned record identifier. type: integer example: 42 nullable: true staged_at: description: Timestamp. type: string format: date-time nullable: true verification_status: description: Display value. type: string example: Example nullable: true type: object nullable: true candidates: type: array items: properties: id: description: Organization-owned record identifier. type: integer example: 42 nullable: false source_name: description: Display value. type: string example: Example nullable: true related_name: description: Display value. type: string example: Example nullable: true relationship_type: description: Display value. type: string example: Example nullable: false is_current: type: boolean example: true available: type: boolean example: true type: object type: object nullable: true IntegrationHubConflictRecurring: description: >- Current recurring-schedule review. When a unique mapped non-charging external commitment exists it is the reviewed commitment; otherwise commitments mapped elsewhere are excluded. Existing commitments/payment behavior are preserved. properties: kind: type: string enum: - recurring_schedule source: properties: provider_object_type: description: Display value. type: string example: Example nullable: true provider_object_id: description: Display value. type: string example: Example nullable: true donor_provider_id: description: Display value. type: string example: Example nullable: true currency: description: Display value. type: string example: Example nullable: true frequency: description: Display value. type: string example: Example nullable: true start_date: description: Display value. type: string example: Example nullable: true end_date: description: Display value. type: string example: Example nullable: true status: description: Display value. type: string example: Example nullable: true last_modified_at: description: Display value. type: string example: Example nullable: true amount: type: number example: 125 nullable: true type: object matched_donor: properties: id: description: Organization-owned record identifier. type: integer example: 42 nullable: false name: description: Display value. type: string example: Example nullable: false type: object nullable: true active_commitments: type: array items: properties: id: description: Organization-owned record identifier. type: integer example: 42 nullable: false amount: type: number example: 125 frequency: description: Display value. type: string example: Example nullable: false is_non_charging: type: boolean example: true is_external_processor: type: boolean example: true type: object active_commitment_count: description: Count. type: integer minimum: 0 example: 2 active_commitment_total: type: number example: 125 mapped_commitment: properties: id: description: Organization-owned record identifier. type: integer example: 42 nullable: false amount: type: number example: 125 frequency: description: Display value. type: string example: Example nullable: false is_non_charging: type: boolean example: true is_external_processor: type: boolean example: true mapping_id: description: Organization-owned record identifier. type: integer example: 42 nullable: false type: object nullable: true can_mark_already_represented: type: boolean example: true expected_provider_object_id: description: Display value. type: string example: Example nullable: false source_snapshot_token: description: Opaque business-state source guard. type: string maxLength: 64 minLength: 64 active_commitment_token: description: Current selected-commitment guard, or null if donor is unavailable. type: string maxLength: 64 minLength: 64 nullable: true type: object nullable: true ValidationErrorResponse: title: ValidationErrorResponse description: >- Returned with HTTP 422 when `Validator::make($data, $rules)` fails. The `errors` map is keyed by the failing field name; each value is an array of human-readable error messages for that field. Most controllers also include a top-level `status: error`. required: - errors properties: errors: description: >- Map of field name to array of validator error messages. Example: `{email: [The email field is required.], amount: [The amount must be a number.]}`. type: object additionalProperties: type: array items: type: string status: description: Always the literal string `error`. type: string example: error message: description: >- Optional summary message — present on some endpoints, absent on others. type: string example: The given data was invalid. nullable: true type: object ErrorResponse: title: ErrorResponse description: >- Generic error envelope used by most controllers. Most error responses pair a human-readable `message` with `status: error`. Some endpoints additionally include `errors` (validator errors), `error` (legacy single-error string), `code`, or domain-specific context fields. required: - message properties: message: description: Human-readable error message. type: string example: Something went wrong. Please try again. status: description: >- Always the literal string `error` for failures. Some endpoints omit this field. type: string example: error error: description: Legacy single error code/string used by older endpoints. type: string example: invalid_request nullable: true code: description: >- Optional application-level error code (not all endpoints populate this). type: string example: DONOR_NOT_FOUND nullable: true type: object securitySchemes: bearerAuth: type: http description: Passport bearer token authentication for legacy admin sessions. scheme: bearer bearerFormat: JWT apiKeyAuth: type: apiKey description: Gratona API key sent with the compatibility header X-HYS-API-Key. name: X-HYS-API-Key in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.