API Reference | MortgageGuidelines API Docs

Public responses include customer-facing identifiers, answer text, sanitized citations, sanitized source summaries, and metadata.tokens_used. Model names, provider details, prompt context, retrieval diagnostics, and internal service configuration are intentionally excluded.

Account

1 endpoint

get/v1/me

Get authenticated API key details

Returns the authenticated public API key summary and client identity.

curl -X GET "https://api.mortgageguidelines.com/v1/me" \
  -H "Authorization: Bearer mgapi_live_your_key_here"

const response = await fetch("https://api.mortgageguidelines.com/v1/me", {
  headers: {
    Authorization: "Bearer mgapi_live_your_key_here",
  },
});

const data = await response.json();

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "key": {
    "id": "pak_test",
    "name": "Example Lender Production",
    "status": "active",
    "scopes": [
      "chat:read",
      "chat:write",
      "sources:read"
    ],
    "last_four": "test",
    "client": {
      "name": "Example Lender",
      "organization": "Example Mortgage Company"
    }
  }
}

Response bodies

200 response schema

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "key": {
    "id": "pak_test",
    "name": "Example Lender Production",
    "status": "active",
    "scopes": [
      "chat:read",
      "chat:write",
      "sources:read"
    ],
    "last_four": "test",
    "client": {
      "name": "Example Lender",
      "organization": "Example Mortgage Company"
    }
  }
}

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "key": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "example": "pak_test"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "example": "Example Lender Production"
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "revoked"
          ],
          "example": "active"
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "example": [
            "chat:read",
            "chat:write",
            "sources:read"
          ]
        },
        "last_four": {
          "type": "string",
          "minLength": 1,
          "example": "test"
        },
        "client": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "example": "Example Lender"
            },
            "organization": {
              "type": "string",
              "example": "Example Mortgage Company"
            }
          },
          "required": [
            "name"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "id",
        "name",
        "status",
        "scopes",
        "last_four",
        "client"
      ]
    }
  },
  "required": [
    "request_id",
    "key"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Discovery

1 endpoint

get/v1/sources

List the sources available to the authenticated API key

Returns selectable agency, tenant, and shared sources available to this API key.

curl -X GET "https://api.mortgageguidelines.com/v1/sources" \
  -H "X-API-Key: mgapi_live_your_key_here"

const response = await fetch("https://api.mortgageguidelines.com/v1/sources", {
  headers: {
    "X-API-Key": "mgapi_live_your_key_here",
  },
});

const data = await response.json();

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "agency_source_types": [
    "fannie_mae",
    "fha"
  ],
  "tenant_source_keys": [
    "product-guides"
  ],
  "tenant_sources": [
    {
      "key": "product-guides",
      "label": "Product Guides",
      "description": "Internal product guidance",
      "defaultOn": true
    }
  ],
  "default_tenant_source_keys": [
    "product-guides"
  ],
  "shared_source_types": [
    "mortgage_guidelines"
  ],
  "shared_sources": [
    {
      "sourceType": "mortgage_guidelines",
      "label": "Mortgage Guidelines",
      "defaultOn": true
    }
  ],
  "default_shared_source_types": [
    "mortgage_guidelines"
  ]
}

Response bodies

200 response schema

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "agency_source_types": [
    "fannie_mae",
    "fha"
  ],
  "tenant_source_keys": [
    "product-guides"
  ],
  "tenant_sources": [
    {
      "key": "product-guides",
      "label": "Product Guides",
      "description": "Internal product guidance",
      "defaultOn": true
    }
  ],
  "default_tenant_source_keys": [
    "product-guides"
  ],
  "shared_source_types": [
    "mortgage_guidelines"
  ],
  "shared_sources": [
    {
      "sourceType": "mortgage_guidelines",
      "label": "Mortgage Guidelines",
      "defaultOn": true
    }
  ],
  "default_shared_source_types": [
    "mortgage_guidelines"
  ]
}

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "agency_source_types": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "fannie_mae",
        "fha"
      ]
    },
    "tenant_source_keys": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "product-guides"
      ]
    },
    "tenant_sources": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "minLength": 1,
            "example": "product-guides"
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "example": "Product Guides"
          },
          "description": {
            "type": "string",
            "example": "Client-specific product guidelines"
          },
          "defaultOn": {
            "type": "boolean",
            "example": true
          }
        },
        "required": [
          "key",
          "label",
          "defaultOn"
        ],
        "additionalProperties": false
      }
    },
    "default_tenant_source_keys": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "product-guides"
      ]
    },
    "shared_source_types": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "mortgage_guidelines"
      ]
    },
    "shared_sources": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sourceType": {
            "type": "string",
            "minLength": 1,
            "example": "mortgage_guidelines"
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "example": "Mortgage Guidelines"
          },
          "description": {
            "type": "string",
            "example": "Shared platform content available to this client"
          },
          "defaultOn": {
            "type": "boolean",
            "example": false
          }
        },
        "required": [
          "sourceType",
          "label",
          "defaultOn"
        ],
        "additionalProperties": false
      }
    },
    "default_shared_source_types": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "mortgage_guidelines"
      ]
    }
  },
  "required": [
    "request_id",
    "agency_source_types",
    "tenant_source_keys",
    "tenant_sources",
    "default_tenant_source_keys",
    "shared_source_types",
    "shared_sources",
    "default_shared_source_types"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Embedded Chat

1 endpoint

post/v1/embed-sessions

Create a one-time embedded chat launch

Authenticates a trusted partner backend and returns a single-use embedded-chat launch URL. The API key must remain server-side.

Notes

The user must already be provisioned and active.
The returned URL expires after two minutes and can be exchanged only once.
Borrower PII, employee identity fields, and financial ratios are not accepted.

Idempotency

Reuse the same Idempotency-Key only when retrying the identical launch request. Use a new key for every new iframe launch.

Request body

Strict provisioned-user identifier and approved non-PII loan context. Desktop integrations omit parent_origin.

{
  "integration": "your_assigned_integration",
  "user": {
    "external_user_id": "partner-user-6d55c95f"
  },
  "loan_context": {
    "external_loan_id": "loan-7f4a2d18",
    "program": "fha",
    "purpose": "purchase",
    "occupancy": "primary_residence",
    "property_type": "single_family",
    "property_state": "TX",
    "units": 1,
    "milestone": "processing",
    "application_date": "2026-07-10"
  }
}

{
  "type": "object",
  "properties": {
    "integration": {
      "type": "string",
      "example": "your_assigned_integration"
    },
    "parent_origin": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri",
      "description": "Exact HTTPS framing origin for origin-bound integrations. Omit this field when the assigned integration uses a desktop-managed host policy.",
      "example": "https://partner.example.com"
    },
    "user": {
      "type": "object",
      "properties": {
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$",
          "description": "Stable opaque identifier assigned to the user by the partner system. Do not send an email address.",
          "example": "partner-user-6d55c95f"
        }
      },
      "required": [
        "external_user_id"
      ],
      "additionalProperties": false
    },
    "loan_context": {
      "type": "object",
      "properties": {
        "external_loan_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$",
          "description": "Opaque loan correlation identifier. Do not send a lender or source-system loan number.",
          "example": "loan-7f4a2d18"
        },
        "program": {
          "type": "string",
          "enum": [
            "conventional",
            "fha",
            "va",
            "usda",
            "other"
          ],
          "example": "fha"
        },
        "purpose": {
          "type": "string",
          "enum": [
            "purchase",
            "rate_term_refinance",
            "cash_out_refinance",
            "construction",
            "other"
          ],
          "example": "purchase"
        },
        "occupancy": {
          "type": "string",
          "enum": [
            "primary_residence",
            "second_home",
            "investment",
            "other"
          ],
          "example": "primary_residence"
        },
        "property_type": {
          "type": "string",
          "enum": [
            "single_family",
            "condominium",
            "townhouse",
            "manufactured_home",
            "two_to_four_unit",
            "other"
          ],
          "example": "single_family"
        },
        "property_state": {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "example": "TX"
        },
        "units": {
          "type": "integer",
          "minimum": 1,
          "maximum": 4,
          "example": 1
        },
        "milestone": {
          "type": "string",
          "enum": [
            "application",
            "processing",
            "underwriting",
            "approved",
            "clear_to_close",
            "closed",
            "other"
          ],
          "example": "processing"
        },
        "application_date": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "example": "2026-07-10"
        }
      },
      "required": [
        "external_loan_id"
      ],
      "additionalProperties": false,
      "description": "Approved non-borrower-PII loan context. Unknown fields are rejected."
    }
  },
  "required": [
    "integration",
    "user",
    "loan_context"
  ],
  "additionalProperties": false
}

curl -X POST "https://api.mortgageguidelines.com/v1/embed-sessions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mgapi_live_your_key_here" \
  -H "Idempotency-Key: partner-launch-6d55c95f-001" \
  -d '{
  "integration": "your_assigned_integration",
  "user": {
    "external_user_id": "partner-user-6d55c95f"
  },
  "loan_context": {
    "external_loan_id": "loan-7f4a2d18",
    "program": "fha",
    "purpose": "purchase",
    "occupancy": "primary_residence",
    "property_type": "single_family",
    "property_state": "TX",
    "units": 1,
    "milestone": "processing",
    "application_date": "2026-07-10"
  }
}'

const response = await fetch("https://api.mortgageguidelines.com/v1/embed-sessions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer mgapi_live_your_key_here",
    "Idempotency-Key": "partner-launch-6d55c95f-001",
  },
  body: JSON.stringify({
  "integration": "your_assigned_integration",
  "user": {
    "external_user_id": "partner-user-6d55c95f"
  },
  "loan_context": {
    "external_loan_id": "loan-7f4a2d18",
    "program": "fha",
    "purpose": "purchase",
    "occupancy": "primary_residence",
    "property_type": "single_family",
    "property_state": "TX",
    "units": 1,
    "milestone": "processing",
    "application_date": "2026-07-10"
  }
}),
});

const data = await response.json();

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "launch_id": "launch_06f22d7e7137e087",
  "launch_url": "https://app.mortgageguidelines.com/embed/partner#launch=one-time-code",
  "expires_at": "2026-07-10T14:02:00.000Z"
}

Response bodies

201 response schema

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "launch_id": "launch_06f22d7e7137e087",
  "launch_url": "https://app.mortgageguidelines.com/embed/partner#launch=one-time-code",
  "expires_at": "2026-07-10T14:02:00.000Z"
}

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "launch_id": {
      "type": "string",
      "minLength": 1,
      "example": "launch_06f22d7e7137e087"
    },
    "launch_url": {
      "type": "string",
      "format": "uri",
      "example": "https://app.mortgageguidelines.com/embed/partner#launch=one-time-code"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-10T14:02:00.000Z"
    }
  },
  "required": [
    "request_id",
    "launch_id",
    "launch_url",
    "expires_at"
  ],
  "additionalProperties": false
}

400 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

409 response schema

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

502 response schema

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Scopes

embed:launch

Headers

Authorization or X-API-Key
Idempotency-Key

Responses

201 One-time iframe launch created successfully.application/json
400 Invalid request body, invalid source selection, or unsupported streaming/idempotency combination.application/json
401 Missing, invalid, or inactive API key.application/json
403 The API key does not include the required scope for this operation.application/json
409 The request conflicts with current state, such as an idempotency-key conflict, immutable identity reassignment, duplicate or in-use team, or assignment to an archived team.application/json
429 The API key exceeded one of its configured rate limits.application/json
500 The service encountered an unexpected internal error. Retry with backoff and provide the returned request ID if the problem persists.application/json
502 The upstream chat service failed or returned an unexpected response.application/json

Partner Teams

4 endpoints

get/v1/integrations/{integration}/teams

List partner teams

Lists organization-scoped partner teams and current assignment counts.

Path and query parameters

integrationpathrequired

Configured partner integration identifier.

{
  "type": "string",
  "example": "your_assigned_integration"
}

statusqueryoptional

{
  "type": "string",
  "enum": [
    "active",
    "archived"
  ]
}

limitqueryoptional

{
  "type": "integer",
  "minimum": 1,
  "maximum": 100,
  "default": 100,
  "example": 100
}

cursorqueryoptional

{
  "type": "string",
  "minLength": 1,
  "maxLength": 1024
}

curl \
  --request GET \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/teams' \
  --header 'Authorization: Bearer $API_KEY'

Response bodies

200 response schema

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "teams": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1
          },
          "integration": {
            "type": "string"
          },
          "external_team_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "archived"
            ]
          },
          "user_count": {
            "type": "integer",
            "minimum": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "integration",
          "external_team_id",
          "name",
          "status",
          "user_count",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "request_id",
    "teams",
    "next_cursor"
  ],
  "additionalProperties": false
}

400 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

502 response schema

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

put/v1/integrations/{integration}/teams/{external_team_id}

Create or match a partner team

Idempotently creates or matches a team. Use PATCH to rename an existing team.

Path and query parameters

integrationpathrequired

Configured partner integration identifier.

{
  "type": "string",
  "example": "your_assigned_integration"
}

external_team_idpathrequired

Stable opaque partner team identifier.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "retail-west"
}

Request body

{
  "name": "Retail West"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "example": "Retail West"
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

curl \
  --request PUT \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/teams/retail-west' \
  --header 'Authorization: Bearer $API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Retail West"
}'

Response bodies

200 response schema

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "team": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "integration": {
          "type": "string"
        },
        "external_team_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "archived"
          ]
        },
        "user_count": {
          "type": "integer",
          "minimum": 0
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "integration",
        "external_team_id",
        "name",
        "status",
        "user_count",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "team"
  ],
  "additionalProperties": false
}

201 response schema

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "team": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "integration": {
          "type": "string"
        },
        "external_team_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "archived"
          ]
        },
        "user_count": {
          "type": "integer",
          "minimum": 0
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "integration",
        "external_team_id",
        "name",
        "status",
        "user_count",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "team"
  ],
  "additionalProperties": false
}

400 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

409 response schema

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

502 response schema

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Scopes

embed:teams:write

Headers

Authorization or X-API-Key

Responses

200 Existing partner team matched.application/json
201 Partner team created.application/json
400 Invalid request body, invalid source selection, or unsupported streaming/idempotency combination.application/json
401 Missing, invalid, or inactive API key.application/json
403 The API key does not include the required scope for this operation.application/json
409 The request conflicts with current state, such as an idempotency-key conflict, immutable identity reassignment, duplicate or in-use team, or assignment to an archived team.application/json
429 The API key exceeded one of its configured rate limits.application/json
500 The service encountered an unexpected internal error. Retry with backoff and provide the returned request ID if the problem persists.application/json
502 The upstream chat service failed or returned an unexpected response.application/json

get/v1/integrations/{integration}/teams/{external_team_id}

Get a partner team

Returns an organization-scoped partner team and its current assignment count.

Path and query parameters

integrationpathrequired

Configured partner integration identifier.

{
  "type": "string",
  "example": "your_assigned_integration"
}

external_team_idpathrequired

Stable opaque partner team identifier.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "retail-west"
}

curl \
  --request GET \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/teams/retail-west' \
  --header 'Authorization: Bearer $API_KEY'

Response bodies

200 response schema

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "team": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "integration": {
          "type": "string"
        },
        "external_team_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "archived"
          ]
        },
        "user_count": {
          "type": "integer",
          "minimum": 0
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "integration",
        "external_team_id",
        "name",
        "status",
        "user_count",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "team"
  ],
  "additionalProperties": false
}

400 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

404 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

502 response schema

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

patch/v1/integrations/{integration}/teams/{external_team_id}

Update or archive a partner team

Renames or archives a team. A team with current or queued assignments cannot be archived.

Path and query parameters

integrationpathrequired

Configured partner integration identifier.

{
  "type": "string",
  "example": "your_assigned_integration"
}

external_team_idpathrequired

Stable opaque partner team identifier.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "retail-west"
}

Request body

{
  "name": "Western Retail"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "example": "Retail West"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "archived"
      ],
      "example": "archived"
    }
  },
  "additionalProperties": false
}

curl \
  --request PATCH \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/teams/retail-west' \
  --header 'Authorization: Bearer $API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Western Retail"
}'

Response bodies

200 response schema

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "team": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "integration": {
          "type": "string"
        },
        "external_team_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "archived"
          ]
        },
        "user_count": {
          "type": "integer",
          "minimum": 0
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "integration",
        "external_team_id",
        "name",
        "status",
        "user_count",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "team"
  ],
  "additionalProperties": false
}

400 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

404 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

409 response schema

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

502 response schema

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Scopes

embed:teams:write

Headers

Authorization or X-API-Key

Responses

200 Partner team updated.application/json
400 Invalid request body, invalid source selection, or unsupported streaming/idempotency combination.application/json
401 Missing, invalid, or inactive API key.application/json
403 The API key does not include the required scope for this operation.application/json
404 The requested resource was not found or is not visible to the authenticated API key.application/json
409 The request conflicts with current state, such as an idempotency-key conflict, immutable identity reassignment, duplicate or in-use team, or assignment to an archived team.application/json
429 The API key exceeded one of its configured rate limits.application/json
500 The service encountered an unexpected internal error. Retry with backoff and provide the returned request ID if the problem persists.application/json
502 The upstream chat service failed or returned an unexpected response.application/json

Partner Users

10 endpoints

get/v1/integrations/{integration}/users

List partner users

Lists sanitized partner-user entitlement, mapping readiness, and current team classification. Deleted users are excluded by default and are returned only when status=deleted is supplied explicitly.

Path and query parameters

integrationpathrequired

Configured partner integration identifier.

{
  "type": "string",
  "example": "your_assigned_integration"
}

qqueryoptional

Case-insensitive partial external user ID. Email addresses are not accepted.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 128
}

external_user_idqueryoptional

{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$"
}

statusqueryoptional

Filter by lifecycle status. Deleted users are excluded unless status=deleted is supplied explicitly.

{
  "type": "string",
  "enum": [
    "active",
    "disabled",
    "deleted"
  ]
}

provisioning_statusqueryoptional

{
  "type": "string",
  "enum": [
    "pending",
    "active",
    "failed"
  ]
}

team_external_idqueryoptional

{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$"
}

unassignedqueryoptional

{
  "type": "string",
  "enum": [
    "true",
    "false"
  ],
  "example": "false"
}

identity_originqueryoptional

{
  "type": "string",
  "enum": [
    "existing_mg",
    "partner_created",
    "unresolved"
  ]
}

experience_typequeryoptional

{
  "type": "string",
  "enum": [
    "mg",
    "white_label"
  ]
}

mapping_statusqueryoptional

{
  "type": "string",
  "enum": [
    "pending",
    "mapped",
    "failed",
    "unmapped"
  ]
}

readinessqueryoptional

{
  "type": "string",
  "enum": [
    "ready",
    "blocked"
  ]
}

limitqueryoptional

{
  "type": "integer",
  "minimum": 1,
  "maximum": 100,
  "default": 25,
  "example": 25
}

cursorqueryoptional

{
  "type": "string",
  "minLength": 1,
  "maxLength": 1024
}

curl \
  --request GET \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/users' \
  --header 'Authorization: Bearer $API_KEY'

Response bodies

200 response schema

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "users": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "integration": {
            "type": "string"
          },
          "external_user_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$"
          },
          "team": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1
              },
              "external_team_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120
              },
              "status": {
                "type": "string",
                "enum": [
                  "active",
                  "archived"
                ]
              }
            },
            "required": [
              "id",
              "external_team_id",
              "name",
              "status"
            ],
            "additionalProperties": false
          },
          "assignment_version": {
            "type": "integer",
            "exclusiveMinimum": 0
          },
          "identity_origin": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "existing_mg",
              "partner_created"
            ]
          },
          "experience_type": {
            "type": "string",
            "enum": [
              "mg",
              "white_label"
            ]
          },
          "mapping_status": {
            "type": "string",
            "enum": [
              "pending",
              "mapped",
              "failed",
              "unmapped"
            ]
          },
          "launch_eligibility": {
            "type": "object",
            "properties": {
              "can_launch": {
                "type": "boolean"
              },
              "blocking_reasons": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "disabled",
                    "deleted",
                    "provisioning_pending",
                    "provisioning_failed",
                    "profile_sync_pending",
                    "profile_sync_failed",
                    "wordpress_sync_pending",
                    "wordpress_sync_failed",
                    "wordpress_unlinked",
                    "chat_identity_unlinked"
                  ]
                }
              }
            },
            "required": [
              "can_launch",
              "blocking_reasons"
            ],
            "additionalProperties": false
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "disabled",
              "deleted"
            ]
          },
          "provisioning_status": {
            "type": "string",
            "enum": [
              "pending",
              "active",
              "failed"
            ]
          },
          "wordpress_linked": {
            "type": "boolean"
          },
          "access_version": {
            "type": "integer",
            "exclusiveMinimum": 0
          },
          "account_generation": {
            "type": "integer",
            "exclusiveMinimum": 0
          },
          "profile_version": {
            "type": "integer",
            "exclusiveMinimum": 0
          },
          "profile_sync_status": {
            "type": "string",
            "enum": [
              "applied",
              "pending",
              "failed"
            ]
          },
          "wordpress_sync_status": {
            "type": "string",
            "enum": [
              "applied",
              "pending",
              "failed"
            ]
          },
          "lifecycle_operation": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "operation_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$"
              },
              "type": {
                "type": "string",
                "enum": [
                  "profile_change",
                  "deletion",
                  "reprovision"
                ]
              },
              "status": {
                "type": "string",
                "enum": [
                  "queued",
                  "verification_pending",
                  "processing",
                  "completed",
                  "failed",
                  "expired",
                  "cancelled"
                ]
              },
              "error_code": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$"
              },
              "updated_at": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "operation_id",
              "type",
              "status",
              "error_code",
              "updated_at"
            ],
            "additionalProperties": false,
            "description": "Sanitized state of the partner user's current lifecycle operation."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "integration",
          "external_user_id",
          "team",
          "assignment_version",
          "identity_origin",
          "experience_type",
          "mapping_status",
          "launch_eligibility",
          "status",
          "provisioning_status",
          "wordpress_linked",
          "access_version",
          "account_generation",
          "profile_version",
          "profile_sync_status",
          "wordpress_sync_status",
          "lifecycle_operation",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "counts": {
      "type": "object",
      "properties": {
        "total": {
          "type": "integer",
          "minimum": 0
        },
        "active": {
          "type": "integer",
          "minimum": 0
        },
        "disabled": {
          "type": "integer",
          "minimum": 0
        },
        "deleted": {
          "type": "integer",
          "minimum": 0
        },
        "pending": {
          "type": "integer",
          "minimum": 0
        },
        "failed": {
          "type": "integer",
          "minimum": 0
        }
      },
      "required": [
        "total",
        "active",
        "disabled",
        "deleted",
        "pending",
        "failed"
      ],
      "additionalProperties": false
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "request_id",
    "users",
    "counts",
    "next_cursor"
  ],
  "additionalProperties": false
}

400 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

502 response schema

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

put/v1/integrations/{integration}/users/{external_user_id}

Provision or match a partner user

Creates or matches the WordPress identity assigned to an immutable opaque partner user ID and can update its team classification. Omit team_external_id to preserve an existing assignment; send null to clear it. A newly created user with no team_external_id is unassigned. A different email for an existing user returns 409; use the profile-change operation instead. Deleted users require the explicit reprovision operation. Passwords are never accepted or returned.

Path and query parameters

integrationpathrequired

Configured partner integration identifier.

{
  "type": "string",
  "example": "your_assigned_integration"
}

external_user_idpathrequired

Stable opaque partner user identifier.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "partner-user-6d55c95f"
}

Request body

The employee identity WordPress should provision or match, plus an optional team assignment. Omission preserves an existing assignment and null clears it.

{
  "email": "taylor.morgan@example.com",
  "name": "Taylor Morgan"
}

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "maxLength": 254,
      "format": "email",
      "example": "employee@example.com"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "example": "Taylor Morgan"
    },
    "team_external_id": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9._:-]+$",
      "description": "Team to assign. Omit to preserve an existing assignment; send null to clear it.",
      "example": "retail-west"
    }
  },
  "required": [
    "email"
  ],
  "additionalProperties": false
}

curl \
  --request PUT \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/users/partner-user-6d55c95f' \
  --header 'Authorization: Bearer $API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "taylor.morgan@example.com",
  "name": "Taylor Morgan"
}'

Response bodies

200 response schema

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "user": {
      "type": "object",
      "properties": {
        "integration": {
          "type": "string"
        },
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "team": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1
            },
            "external_team_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "status": {
              "type": "string",
              "enum": [
                "active",
                "archived"
              ]
            }
          },
          "required": [
            "id",
            "external_team_id",
            "name",
            "status"
          ],
          "additionalProperties": false
        },
        "assignment_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "identity_origin": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "existing_mg",
            "partner_created"
          ]
        },
        "experience_type": {
          "type": "string",
          "enum": [
            "mg",
            "white_label"
          ]
        },
        "mapping_status": {
          "type": "string",
          "enum": [
            "pending",
            "mapped",
            "failed",
            "unmapped"
          ]
        },
        "launch_eligibility": {
          "type": "object",
          "properties": {
            "can_launch": {
              "type": "boolean"
            },
            "blocking_reasons": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "disabled",
                  "deleted",
                  "provisioning_pending",
                  "provisioning_failed",
                  "profile_sync_pending",
                  "profile_sync_failed",
                  "wordpress_sync_pending",
                  "wordpress_sync_failed",
                  "wordpress_unlinked",
                  "chat_identity_unlinked"
                ]
              }
            }
          },
          "required": [
            "can_launch",
            "blocking_reasons"
          ],
          "additionalProperties": false
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "disabled",
            "deleted"
          ]
        },
        "provisioning_status": {
          "type": "string",
          "enum": [
            "pending",
            "active",
            "failed"
          ]
        },
        "wordpress_linked": {
          "type": "boolean"
        },
        "access_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "account_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "wordpress_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "lifecycle_operation": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "operation_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "type": {
              "type": "string",
              "enum": [
                "profile_change",
                "deletion",
                "reprovision"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "queued",
                "verification_pending",
                "processing",
                "completed",
                "failed",
                "expired",
                "cancelled"
              ]
            },
            "error_code": {
              "type": [
                "string",
                "null"
              ],
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "updated_at": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": [
            "operation_id",
            "type",
            "status",
            "error_code",
            "updated_at"
          ],
          "additionalProperties": false,
          "description": "Sanitized state of the partner user's current lifecycle operation."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "integration",
        "external_user_id",
        "team",
        "assignment_version",
        "identity_origin",
        "experience_type",
        "mapping_status",
        "launch_eligibility",
        "status",
        "provisioning_status",
        "wordpress_linked",
        "access_version",
        "account_generation",
        "profile_version",
        "profile_sync_status",
        "wordpress_sync_status",
        "lifecycle_operation",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "user"
  ],
  "additionalProperties": false
}

201 response schema

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "user": {
      "type": "object",
      "properties": {
        "integration": {
          "type": "string"
        },
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "team": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1
            },
            "external_team_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "status": {
              "type": "string",
              "enum": [
                "active",
                "archived"
              ]
            }
          },
          "required": [
            "id",
            "external_team_id",
            "name",
            "status"
          ],
          "additionalProperties": false
        },
        "assignment_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "identity_origin": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "existing_mg",
            "partner_created"
          ]
        },
        "experience_type": {
          "type": "string",
          "enum": [
            "mg",
            "white_label"
          ]
        },
        "mapping_status": {
          "type": "string",
          "enum": [
            "pending",
            "mapped",
            "failed",
            "unmapped"
          ]
        },
        "launch_eligibility": {
          "type": "object",
          "properties": {
            "can_launch": {
              "type": "boolean"
            },
            "blocking_reasons": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "disabled",
                  "deleted",
                  "provisioning_pending",
                  "provisioning_failed",
                  "profile_sync_pending",
                  "profile_sync_failed",
                  "wordpress_sync_pending",
                  "wordpress_sync_failed",
                  "wordpress_unlinked",
                  "chat_identity_unlinked"
                ]
              }
            }
          },
          "required": [
            "can_launch",
            "blocking_reasons"
          ],
          "additionalProperties": false
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "disabled",
            "deleted"
          ]
        },
        "provisioning_status": {
          "type": "string",
          "enum": [
            "pending",
            "active",
            "failed"
          ]
        },
        "wordpress_linked": {
          "type": "boolean"
        },
        "access_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "account_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "wordpress_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "lifecycle_operation": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "operation_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "type": {
              "type": "string",
              "enum": [
                "profile_change",
                "deletion",
                "reprovision"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "queued",
                "verification_pending",
                "processing",
                "completed",
                "failed",
                "expired",
                "cancelled"
              ]
            },
            "error_code": {
              "type": [
                "string",
                "null"
              ],
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "updated_at": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": [
            "operation_id",
            "type",
            "status",
            "error_code",
            "updated_at"
          ],
          "additionalProperties": false,
          "description": "Sanitized state of the partner user's current lifecycle operation."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "integration",
        "external_user_id",
        "team",
        "assignment_version",
        "identity_origin",
        "experience_type",
        "mapping_status",
        "launch_eligibility",
        "status",
        "provisioning_status",
        "wordpress_linked",
        "access_version",
        "account_generation",
        "profile_version",
        "profile_sync_status",
        "wordpress_sync_status",
        "lifecycle_operation",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "user"
  ],
  "additionalProperties": false
}

202 response schema

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "user": {
      "type": "object",
      "properties": {
        "integration": {
          "type": "string"
        },
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "team": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1
            },
            "external_team_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "status": {
              "type": "string",
              "enum": [
                "active",
                "archived"
              ]
            }
          },
          "required": [
            "id",
            "external_team_id",
            "name",
            "status"
          ],
          "additionalProperties": false
        },
        "assignment_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "identity_origin": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "existing_mg",
            "partner_created"
          ]
        },
        "experience_type": {
          "type": "string",
          "enum": [
            "mg",
            "white_label"
          ]
        },
        "mapping_status": {
          "type": "string",
          "enum": [
            "pending",
            "mapped",
            "failed",
            "unmapped"
          ]
        },
        "launch_eligibility": {
          "type": "object",
          "properties": {
            "can_launch": {
              "type": "boolean"
            },
            "blocking_reasons": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "disabled",
                  "deleted",
                  "provisioning_pending",
                  "provisioning_failed",
                  "profile_sync_pending",
                  "profile_sync_failed",
                  "wordpress_sync_pending",
                  "wordpress_sync_failed",
                  "wordpress_unlinked",
                  "chat_identity_unlinked"
                ]
              }
            }
          },
          "required": [
            "can_launch",
            "blocking_reasons"
          ],
          "additionalProperties": false
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "disabled",
            "deleted"
          ]
        },
        "provisioning_status": {
          "type": "string",
          "enum": [
            "pending",
            "active",
            "failed"
          ]
        },
        "wordpress_linked": {
          "type": "boolean"
        },
        "access_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "account_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "wordpress_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "lifecycle_operation": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "operation_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "type": {
              "type": "string",
              "enum": [
                "profile_change",
                "deletion",
                "reprovision"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "queued",
                "verification_pending",
                "processing",
                "completed",
                "failed",
                "expired",
                "cancelled"
              ]
            },
            "error_code": {
              "type": [
                "string",
                "null"
              ],
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "updated_at": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": [
            "operation_id",
            "type",
            "status",
            "error_code",
            "updated_at"
          ],
          "additionalProperties": false,
          "description": "Sanitized state of the partner user's current lifecycle operation."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "integration",
        "external_user_id",
        "team",
        "assignment_version",
        "identity_origin",
        "experience_type",
        "mapping_status",
        "launch_eligibility",
        "status",
        "provisioning_status",
        "wordpress_linked",
        "access_version",
        "account_generation",
        "profile_version",
        "profile_sync_status",
        "wordpress_sync_status",
        "lifecycle_operation",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "user"
  ],
  "additionalProperties": false
}

400 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

404 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

409 response schema

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

502 response schema

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Scopes

embed:users:write

Headers

Authorization or X-API-Key

Responses

200 The existing identity matches.application/json
201 The identity was provisioned.application/json
202 Transient WordPress work was queued.application/json
400 Invalid request body, invalid source selection, or unsupported streaming/idempotency combination.application/json
401 Missing, invalid, or inactive API key.application/json
403 The API key does not include the required scope for this operation.application/json
404 The requested resource was not found or is not visible to the authenticated API key.application/json
409 The request conflicts with current state, such as an idempotency-key conflict, immutable identity reassignment, duplicate or in-use team, or assignment to an archived team.application/json
429 The API key exceeded one of its configured rate limits.application/json
500 The service encountered an unexpected internal error. Retry with backoff and provide the returned request ID if the problem persists.application/json
502 The upstream chat service failed or returned an unexpected response.application/json

get/v1/integrations/{integration}/users/{external_user_id}

Get partner-user access status

Returns sanitized entitlement status without names, email addresses, passwords, or WordPress IDs.

Path and query parameters

integrationpathrequired

Configured partner integration identifier.

{
  "type": "string",
  "example": "your_assigned_integration"
}

external_user_idpathrequired

Stable opaque partner user identifier.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "partner-user-6d55c95f"
}

curl \
  --request GET \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/users/partner-user-6d55c95f' \
  --header 'Authorization: Bearer $API_KEY'

Response bodies

200 response schema

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "user": {
      "type": "object",
      "properties": {
        "integration": {
          "type": "string"
        },
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "team": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1
            },
            "external_team_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "status": {
              "type": "string",
              "enum": [
                "active",
                "archived"
              ]
            }
          },
          "required": [
            "id",
            "external_team_id",
            "name",
            "status"
          ],
          "additionalProperties": false
        },
        "assignment_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "identity_origin": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "existing_mg",
            "partner_created"
          ]
        },
        "experience_type": {
          "type": "string",
          "enum": [
            "mg",
            "white_label"
          ]
        },
        "mapping_status": {
          "type": "string",
          "enum": [
            "pending",
            "mapped",
            "failed",
            "unmapped"
          ]
        },
        "launch_eligibility": {
          "type": "object",
          "properties": {
            "can_launch": {
              "type": "boolean"
            },
            "blocking_reasons": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "disabled",
                  "deleted",
                  "provisioning_pending",
                  "provisioning_failed",
                  "profile_sync_pending",
                  "profile_sync_failed",
                  "wordpress_sync_pending",
                  "wordpress_sync_failed",
                  "wordpress_unlinked",
                  "chat_identity_unlinked"
                ]
              }
            }
          },
          "required": [
            "can_launch",
            "blocking_reasons"
          ],
          "additionalProperties": false
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "disabled",
            "deleted"
          ]
        },
        "provisioning_status": {
          "type": "string",
          "enum": [
            "pending",
            "active",
            "failed"
          ]
        },
        "wordpress_linked": {
          "type": "boolean"
        },
        "access_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "account_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "wordpress_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "lifecycle_operation": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "operation_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "type": {
              "type": "string",
              "enum": [
                "profile_change",
                "deletion",
                "reprovision"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "queued",
                "verification_pending",
                "processing",
                "completed",
                "failed",
                "expired",
                "cancelled"
              ]
            },
            "error_code": {
              "type": [
                "string",
                "null"
              ],
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "updated_at": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": [
            "operation_id",
            "type",
            "status",
            "error_code",
            "updated_at"
          ],
          "additionalProperties": false,
          "description": "Sanitized state of the partner user's current lifecycle operation."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "integration",
        "external_user_id",
        "team",
        "assignment_version",
        "identity_origin",
        "experience_type",
        "mapping_status",
        "launch_eligibility",
        "status",
        "provisioning_status",
        "wordpress_linked",
        "access_version",
        "account_generation",
        "profile_version",
        "profile_sync_status",
        "wordpress_sync_status",
        "lifecycle_operation",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "user"
  ],
  "additionalProperties": false
}

400 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

404 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

502 response schema

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

patch/v1/integrations/{integration}/users/{external_user_id}

Update partner-user access or team

Soft-disables or re-enables MG access and can update the user's team classification. Omit team_external_id to preserve the current assignment; send null to clear it. Disabling revokes active grants immediately and locks partner-created WordPress accounts; existing MG accounts retain unrelated WordPress access. Deleted users cannot be reactivated with this route.

Path and query parameters

integrationpathrequired

Configured partner integration identifier.

{
  "type": "string",
  "example": "your_assigned_integration"
}

external_user_idpathrequired

Stable opaque partner user identifier.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "partner-user-6d55c95f"
}

Request body

The desired entitlement status and/or team assignment. Omission preserves the current team and null clears it.

{
  "status": "disabled"
}

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ],
      "example": "disabled"
    },
    "team_external_id": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9._:-]+$",
      "description": "Team to assign. Omit to preserve the current assignment; send null to clear it.",
      "example": "retail-west"
    }
  },
  "additionalProperties": false
}

curl \
  --request PATCH \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/users/partner-user-6d55c95f' \
  --header 'Authorization: Bearer $API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "status": "disabled"
}'

Response bodies

200 response schema

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "user": {
      "type": "object",
      "properties": {
        "integration": {
          "type": "string"
        },
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "team": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1
            },
            "external_team_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "status": {
              "type": "string",
              "enum": [
                "active",
                "archived"
              ]
            }
          },
          "required": [
            "id",
            "external_team_id",
            "name",
            "status"
          ],
          "additionalProperties": false
        },
        "assignment_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "identity_origin": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "existing_mg",
            "partner_created"
          ]
        },
        "experience_type": {
          "type": "string",
          "enum": [
            "mg",
            "white_label"
          ]
        },
        "mapping_status": {
          "type": "string",
          "enum": [
            "pending",
            "mapped",
            "failed",
            "unmapped"
          ]
        },
        "launch_eligibility": {
          "type": "object",
          "properties": {
            "can_launch": {
              "type": "boolean"
            },
            "blocking_reasons": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "disabled",
                  "deleted",
                  "provisioning_pending",
                  "provisioning_failed",
                  "profile_sync_pending",
                  "profile_sync_failed",
                  "wordpress_sync_pending",
                  "wordpress_sync_failed",
                  "wordpress_unlinked",
                  "chat_identity_unlinked"
                ]
              }
            }
          },
          "required": [
            "can_launch",
            "blocking_reasons"
          ],
          "additionalProperties": false
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "disabled",
            "deleted"
          ]
        },
        "provisioning_status": {
          "type": "string",
          "enum": [
            "pending",
            "active",
            "failed"
          ]
        },
        "wordpress_linked": {
          "type": "boolean"
        },
        "access_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "account_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "wordpress_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "lifecycle_operation": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "operation_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "type": {
              "type": "string",
              "enum": [
                "profile_change",
                "deletion",
                "reprovision"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "queued",
                "verification_pending",
                "processing",
                "completed",
                "failed",
                "expired",
                "cancelled"
              ]
            },
            "error_code": {
              "type": [
                "string",
                "null"
              ],
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "updated_at": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": [
            "operation_id",
            "type",
            "status",
            "error_code",
            "updated_at"
          ],
          "additionalProperties": false,
          "description": "Sanitized state of the partner user's current lifecycle operation."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "integration",
        "external_user_id",
        "team",
        "assignment_version",
        "identity_origin",
        "experience_type",
        "mapping_status",
        "launch_eligibility",
        "status",
        "provisioning_status",
        "wordpress_linked",
        "access_version",
        "account_generation",
        "profile_version",
        "profile_sync_status",
        "wordpress_sync_status",
        "lifecycle_operation",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "user"
  ],
  "additionalProperties": false
}

400 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

404 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

409 response schema

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

502 response schema

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Scopes

embed:users:write

Headers

Authorization or X-API-Key

Responses

200 Partner-user access or team updated.application/json
400 Invalid request body, invalid source selection, or unsupported streaming/idempotency combination.application/json
401 Missing, invalid, or inactive API key.application/json
403 The API key does not include the required scope for this operation.application/json
404 The requested resource was not found or is not visible to the authenticated API key.application/json
409 The request conflicts with current state, such as an idempotency-key conflict, immutable identity reassignment, duplicate or in-use team, or assignment to an archived team.application/json
429 The API key exceeded one of its configured rate limits.application/json
500 The service encountered an unexpected internal error. Retry with backoff and provide the returned request ID if the problem persists.application/json
502 The upstream chat service failed or returned an unexpected response.application/json

post/v1/integrations/{integration}/user-imports

Queue a bulk partner-user import

Queues up to 1,000 unique partner users for bounded asynchronous WordPress provisioning.

Idempotency

Idempotency-Key is required. Reuse it only for the identical import payload.

Path and query parameters

integrationpathrequired

Configured partner integration identifier.

{
  "type": "string",
  "example": "your_assigned_integration"
}

Request body

Unique partner users to provision.

{
  "users": [
    {
      "external_user_id": "partner-user-6d55c95f",
      "email": "taylor.morgan@example.com",
      "name": "Taylor Morgan"
    },
    {
      "external_user_id": "partner-user-10a3c2b1",
      "email": "alex.lee@example.com",
      "name": "Alex Lee"
    }
  ]
}

{
  "type": "object",
  "properties": {
    "users": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "external_user_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "example": "partner-user-6d55c95f"
          },
          "email": {
            "type": "string",
            "maxLength": 254,
            "format": "email",
            "example": "employee@example.com"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "example": "Taylor Morgan"
          },
          "team_external_id": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Team to assign. Omit to preserve an existing assignment; send null to clear it.",
            "example": "retail-west"
          }
        },
        "required": [
          "external_user_id",
          "email"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 1000
    }
  },
  "required": [
    "users"
  ],
  "additionalProperties": false
}

curl \
  --request POST \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/user-imports' \
  --header 'Authorization: Bearer $API_KEY' \
  --header 'Idempotency-Key: replace-with-a-unique-key' \
  --header 'Content-Type: application/json' \
  --data '{
  "users": [
    {
      "external_user_id": "partner-user-6d55c95f",
      "email": "taylor.morgan@example.com",
      "name": "Taylor Morgan"
    },
    {
      "external_user_id": "partner-user-10a3c2b1",
      "email": "alex.lee@example.com",
      "name": "Alex Lee"
    }
  ]
}'

Response bodies

202 response schema

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "job_id": {
      "type": "string",
      "minLength": 1
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "processing",
        "completed",
        "completed_with_errors"
      ]
    },
    "total": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    }
  },
  "required": [
    "request_id",
    "job_id",
    "status",
    "total"
  ],
  "additionalProperties": false
}

400 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

409 response schema

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

502 response schema

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Scopes

embed:users:write

Headers

Authorization or X-API-Key
Idempotency-Key

Responses

202 The import was queued.application/json
400 Invalid request body, invalid source selection, or unsupported streaming/idempotency combination.application/json
401 Missing, invalid, or inactive API key.application/json
403 The API key does not include the required scope for this operation.application/json
409 The request conflicts with current state, such as an idempotency-key conflict, immutable identity reassignment, duplicate or in-use team, or assignment to an archived team.application/json
429 The API key exceeded one of its configured rate limits.application/json
500 The service encountered an unexpected internal error. Retry with backoff and provide the returned request ID if the problem persists.application/json
502 The upstream chat service failed or returned an unexpected response.application/json

post/v1/integrations/{integration}/users/{external_user_id}/profile-changes

Change a partner user's profile

Queues a versioned email and/or display-name change for the exact mapped identity. Partner-created identities process directly. Existing MG email changes enter verification_pending for up to 24 hours; existing-MG name-only changes require an audited MG-admin override. Ordinary provisioning never performs this change.

Idempotency

Idempotency-Key is required. Reuse it only for the identical profile-change payload.

Path and query parameters

integrationpathrequired

Configured partner integration identifier.

{
  "type": "string",
  "example": "your_assigned_integration"
}

external_user_idpathrequired

Stable opaque partner user identifier.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "partner-user-6d55c95f"
}

Request body

At least one new profile field. The immutable external_user_id is never changed.

{
  "email": "taylor.wilson@example.com",
  "name": "Taylor Wilson"
}

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "maxLength": 254,
      "format": "email",
      "example": "taylor.wilson@example.com"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "example": "Taylor Wilson"
    }
  },
  "additionalProperties": false
}

curl \
  --request POST \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/users/partner-user-6d55c95f/profile-changes' \
  --header 'Authorization: Bearer $API_KEY' \
  --header 'Idempotency-Key: replace-with-a-unique-key' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "taylor.wilson@example.com",
  "name": "Taylor Wilson"
}'

Response bodies

202 response schema

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "operation": {
    "operation_id": "pop_06f22d7e7137e087",
    "integration": "your_assigned_integration",
    "external_user_id": "partner-user-6d55c95f",
    "type": "profile_change",
    "status": "verification_pending",
    "account_generation": 1,
    "error_code": null,
    "verification_expires_at": "2026-07-11T14:02:00.000Z",
    "created_at": "2026-07-10T14:02:00.000Z",
    "updated_at": "2026-07-10T14:02:00.000Z",
    "completed_at": null
  }
}

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "operation": {
      "type": "object",
      "properties": {
        "operation_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "integration": {
          "type": "string"
        },
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "type": {
          "type": "string",
          "enum": [
            "profile_change",
            "deletion",
            "reprovision"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "verification_pending",
            "processing",
            "completed",
            "failed",
            "expired",
            "cancelled"
          ]
        },
        "account_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "error_code": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "verification_expires_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "completed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "required": [
        "operation_id",
        "integration",
        "external_user_id",
        "type",
        "status",
        "account_generation",
        "error_code",
        "verification_expires_at",
        "created_at",
        "updated_at",
        "completed_at"
      ],
      "additionalProperties": false,
      "description": "Sanitized partner-user lifecycle operation. Identity values, verification secrets, and audit notes are never returned."
    }
  },
  "required": [
    "request_id",
    "operation"
  ],
  "additionalProperties": false
}

400 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

404 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

409 response schema

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

502 response schema

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Scopes

embed:users:write

Headers

Authorization or X-API-Key
Idempotency-Key

Responses

202 The profile change was accepted for processing or verification.application/json
400 Invalid request body, invalid source selection, or unsupported streaming/idempotency combination.application/json
401 Missing, invalid, or inactive API key.application/json
403 The API key does not include the required scope for this operation.application/json
404 The requested resource was not found or is not visible to the authenticated API key.application/json
409 The request conflicts with current state, such as an idempotency-key conflict, immutable identity reassignment, duplicate or in-use team, or assignment to an archived team.application/json
429 The API key exceeded one of its configured rate limits.application/json
500 The service encountered an unexpected internal error. Retry with backoff and provide the returned request ID if the problem persists.application/json
502 The upstream chat service failed or returned an unexpected response.application/json

post/v1/integrations/{integration}/users/{external_user_id}/deletions

Permanently delete a partner account

Immediately disables access and queues permanent account deletion without notifying the user. Identified audit and conversation history is retained indefinitely; the optional audit note is never returned by the public API.

Idempotency

Idempotency-Key is required. Reuse it only for the identical deletion request.

Path and query parameters

integrationpathrequired

Configured partner integration identifier.

{
  "type": "string",
  "example": "your_assigned_integration"
}

external_user_idpathrequired

Stable opaque partner user identifier.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "partner-user-6d55c95f"
}

Request body

An optional audit note. Send an empty object when no note is needed.

{
  "note": "Employment ended"
}

{
  "type": "object",
  "properties": {
    "note": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000,
      "description": "Optional audit note. It is retained for authorized audit viewers and is not returned by the public API.",
      "example": "Employment ended"
    }
  },
  "additionalProperties": false
}

curl \
  --request POST \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/users/partner-user-6d55c95f/deletions' \
  --header 'Authorization: Bearer $API_KEY' \
  --header 'Idempotency-Key: replace-with-a-unique-key' \
  --header 'Content-Type: application/json' \
  --data '{
  "note": "Employment ended"
}'

Response bodies

202 response schema

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "operation": {
    "operation_id": "pop_16e33e8f8248f198",
    "integration": "your_assigned_integration",
    "external_user_id": "partner-user-6d55c95f",
    "type": "deletion",
    "status": "queued",
    "account_generation": 1,
    "error_code": null,
    "verification_expires_at": null,
    "created_at": "2026-07-10T14:02:00.000Z",
    "updated_at": "2026-07-10T14:02:00.000Z",
    "completed_at": null
  }
}

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "operation": {
      "type": "object",
      "properties": {
        "operation_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "integration": {
          "type": "string"
        },
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "type": {
          "type": "string",
          "enum": [
            "profile_change",
            "deletion",
            "reprovision"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "verification_pending",
            "processing",
            "completed",
            "failed",
            "expired",
            "cancelled"
          ]
        },
        "account_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "error_code": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "verification_expires_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "completed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "required": [
        "operation_id",
        "integration",
        "external_user_id",
        "type",
        "status",
        "account_generation",
        "error_code",
        "verification_expires_at",
        "created_at",
        "updated_at",
        "completed_at"
      ],
      "additionalProperties": false,
      "description": "Sanitized partner-user lifecycle operation. Identity values, verification secrets, and audit notes are never returned."
    }
  },
  "required": [
    "request_id",
    "operation"
  ],
  "additionalProperties": false
}

400 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

404 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

409 response schema

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

502 response schema

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Scopes

embed:users:delete

Headers

Authorization or X-API-Key
Idempotency-Key

Responses

202 Access was revoked and account deletion was queued.application/json
400 Invalid request body, invalid source selection, or unsupported streaming/idempotency combination.application/json
401 Missing, invalid, or inactive API key.application/json
403 The API key does not include the required scope for this operation.application/json
404 The requested resource was not found or is not visible to the authenticated API key.application/json
409 The request conflicts with current state, such as an idempotency-key conflict, immutable identity reassignment, duplicate or in-use team, or assignment to an archived team.application/json
429 The API key exceeded one of its configured rate limits.application/json
500 The service encountered an unexpected internal error. Retry with backoff and provide the returned request ID if the problem persists.application/json
502 The upstream chat service failed or returned an unexpected response.application/json

post/v1/integrations/{integration}/users/{external_user_id}/reprovision

Reprovision a deleted partner user

Creates a new account generation for a deleted external user ID. The returning user receives new WordPress and chat identities and cannot access earlier-generation conversations.

Idempotency

Idempotency-Key is required. Reuse it only for the identical reprovision request.

Path and query parameters

integrationpathrequired

Configured partner integration identifier.

{
  "type": "string",
  "example": "your_assigned_integration"
}

external_user_idpathrequired

Stable opaque partner user identifier.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "partner-user-6d55c95f"
}

Request body

Identity and optional team assignment for the new account generation.

{
  "email": "taylor.returned@example.com",
  "name": "Taylor Wilson",
  "team_external_id": "retail-west"
}

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "maxLength": 254,
      "format": "email",
      "example": "returning.employee@example.com"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "example": "Taylor Wilson"
    },
    "team_external_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9._:-]+$",
      "description": "Team to assign to the new account generation. Omit to start unassigned.",
      "example": "retail-west"
    }
  },
  "required": [
    "email"
  ],
  "additionalProperties": false,
  "description": "Identity and optional team assignment for a new account generation of a deleted partner user."
}

curl \
  --request POST \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/users/partner-user-6d55c95f/reprovision' \
  --header 'Authorization: Bearer $API_KEY' \
  --header 'Idempotency-Key: replace-with-a-unique-key' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "taylor.returned@example.com",
  "name": "Taylor Wilson",
  "team_external_id": "retail-west"
}'

Response bodies

202 response schema

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "operation": {
    "operation_id": "pop_66f930b80ca0402a",
    "integration": "your_assigned_integration",
    "external_user_id": "partner-user-6d55c95f",
    "type": "reprovision",
    "status": "queued",
    "account_generation": 2,
    "error_code": null,
    "verification_expires_at": null,
    "created_at": "2026-07-10T14:02:00.000Z",
    "updated_at": "2026-07-10T14:02:00.000Z",
    "completed_at": null
  }
}

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "operation": {
      "type": "object",
      "properties": {
        "operation_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "integration": {
          "type": "string"
        },
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "type": {
          "type": "string",
          "enum": [
            "profile_change",
            "deletion",
            "reprovision"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "verification_pending",
            "processing",
            "completed",
            "failed",
            "expired",
            "cancelled"
          ]
        },
        "account_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "error_code": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "verification_expires_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "completed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "required": [
        "operation_id",
        "integration",
        "external_user_id",
        "type",
        "status",
        "account_generation",
        "error_code",
        "verification_expires_at",
        "created_at",
        "updated_at",
        "completed_at"
      ],
      "additionalProperties": false,
      "description": "Sanitized partner-user lifecycle operation. Identity values, verification secrets, and audit notes are never returned."
    }
  },
  "required": [
    "request_id",
    "operation"
  ],
  "additionalProperties": false
}

400 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

404 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

409 response schema

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

502 response schema

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Scopes

embed:users:write

Headers

Authorization or X-API-Key
Idempotency-Key

Responses

202 The new account generation was accepted for provisioning.application/json
400 Invalid request body, invalid source selection, or unsupported streaming/idempotency combination.application/json
401 Missing, invalid, or inactive API key.application/json
403 The API key does not include the required scope for this operation.application/json
404 The requested resource was not found or is not visible to the authenticated API key.application/json
409 The request conflicts with current state, such as an idempotency-key conflict, immutable identity reassignment, duplicate or in-use team, or assignment to an archived team.application/json
429 The API key exceeded one of its configured rate limits.application/json
500 The service encountered an unexpected internal error. Retry with backoff and provide the returned request ID if the problem persists.application/json
502 The upstream chat service failed or returned an unexpected response.application/json

get/v1/integrations/{integration}/user-operations/{operation_id}

Get a partner-user lifecycle operation

Returns sanitized deletion, profile-change, or reprovision progress. Audit notes, identity values, and verification secrets are never returned.

Path and query parameters

integrationpathrequired

Configured partner integration identifier.

{
  "type": "string",
  "example": "your_assigned_integration"
}

operation_idpathrequired

Partner-user lifecycle operation identifier.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "pop_06f22d7e7137e087"
}

curl \
  --request GET \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/user-operations/pop_06f22d7e7137e087' \
  --header 'Authorization: Bearer $API_KEY'

Response bodies

200 response schema

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "operation": {
    "operation_id": "pop_06f22d7e7137e087",
    "integration": "your_assigned_integration",
    "external_user_id": "partner-user-6d55c95f",
    "type": "profile_change",
    "status": "verification_pending",
    "account_generation": 1,
    "error_code": null,
    "verification_expires_at": "2026-07-11T14:02:00.000Z",
    "created_at": "2026-07-10T14:02:00.000Z",
    "updated_at": "2026-07-10T14:02:00.000Z",
    "completed_at": null
  }
}

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "operation": {
      "type": "object",
      "properties": {
        "operation_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "integration": {
          "type": "string"
        },
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "type": {
          "type": "string",
          "enum": [
            "profile_change",
            "deletion",
            "reprovision"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "verification_pending",
            "processing",
            "completed",
            "failed",
            "expired",
            "cancelled"
          ]
        },
        "account_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "error_code": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "verification_expires_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "completed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "required": [
        "operation_id",
        "integration",
        "external_user_id",
        "type",
        "status",
        "account_generation",
        "error_code",
        "verification_expires_at",
        "created_at",
        "updated_at",
        "completed_at"
      ],
      "additionalProperties": false,
      "description": "Sanitized partner-user lifecycle operation. Identity values, verification secrets, and audit notes are never returned."
    }
  },
  "required": [
    "request_id",
    "operation"
  ],
  "additionalProperties": false
}

400 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

404 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

502 response schema

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Scopes

embed:users:read

Headers

Authorization or X-API-Key

Responses

200 Current lifecycle-operation status.application/json
400 Invalid request body, invalid source selection, or unsupported streaming/idempotency combination.application/json
401 Missing, invalid, or inactive API key.application/json
403 The API key does not include the required scope for this operation.application/json
404 The requested resource was not found or is not visible to the authenticated API key.application/json
429 The API key exceeded one of its configured rate limits.application/json
500 The service encountered an unexpected internal error. Retry with backoff and provide the returned request ID if the problem persists.application/json
502 The upstream chat service failed or returned an unexpected response.application/json

get/v1/integrations/{integration}/user-imports/{job_id}

Get bulk import progress and sanitized results

Returns paginated per-user results. Identity data and encrypted work payloads are never returned.

Path and query parameters

integrationpathrequired

Configured partner integration identifier.

{
  "type": "string",
  "example": "your_assigned_integration"
}

job_idpathrequired

Provisioning import job identifier.

{
  "type": "string",
  "pattern": "^pjob_[A-Za-z0-9_-]{8,80}$",
  "example": "pjob_06f22d7e7137e087"
}

pagequeryoptional

{
  "type": "integer",
  "exclusiveMinimum": 0,
  "default": 1,
  "example": 1
}

per_pagequeryoptional

{
  "type": "integer",
  "minimum": 1,
  "maximum": 100,
  "default": 100,
  "example": 100
}

curl \
  --request GET \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/user-imports/pjob_06f22d7e7137e087' \
  --header 'Authorization: Bearer $API_KEY'

Response bodies

200 response schema

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "job_id": {
      "type": "string",
      "minLength": 1
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "processing",
        "completed",
        "completed_with_errors"
      ]
    },
    "total": {
      "type": "integer",
      "minimum": 0
    },
    "completed": {
      "type": "integer",
      "minimum": 0
    },
    "failed": {
      "type": "integer",
      "minimum": 0
    },
    "page": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "external_user_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "processing",
              "created",
              "matched",
              "failed"
            ]
          },
          "error_code": {
            "type": "string",
            "enum": [
              "identity_conflict",
              "wordpress_unavailable",
              "provisioning_failed",
              "team_not_found",
              "team_archived"
            ]
          }
        },
        "required": [
          "external_user_id",
          "status"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "request_id",
    "job_id",
    "status",
    "total",
    "completed",
    "failed",
    "page",
    "per_page",
    "results"
  ],
  "additionalProperties": false
}

400 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

404 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

502 response schema

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Scopes

embed:users:read

Headers

Authorization or X-API-Key

Responses

200 Current import status and results.application/json
400 Invalid request body, invalid source selection, or unsupported streaming/idempotency combination.application/json
401 Missing, invalid, or inactive API key.application/json
403 The API key does not include the required scope for this operation.application/json
404 The requested resource was not found or is not visible to the authenticated API key.application/json
429 The API key exceeded one of its configured rate limits.application/json
500 The service encountered an unexpected internal error. Retry with backoff and provide the returned request ID if the problem persists.application/json
502 The upstream chat service failed or returned an unexpected response.application/json

Conversations

3 endpoints

post/v1/conversations

Create a conversation explicitly

Creates a conversation before sending any assistant messages. Use this when you need a stable conversation ID up front.

Idempotency

`Idempotency-Key` is supported for non-streaming POST requests so that safe retries return the original completed response.

Request body

Conversation creation payload.

{
  "title": "FHA gift funds",
  "user": {
    "external_user_id": "user_123",
    "email": "user@example.com",
    "name": "Test User"
  },
  "metadata": {
    "external_ticket_id": "ticket_789"
  }
}

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Optional conversation title.",
      "example": "FHA gift funds"
    },
    "user": {
      "type": "object",
      "properties": {
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "description": "Stable identifier from your system for the end user.",
          "example": "user_123"
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Optional email address for the external user.",
          "example": "user@example.com"
        },
        "name": {
          "type": "string",
          "description": "Optional display name for the external user.",
          "example": "Test User"
        }
      },
      "required": [
        "external_user_id"
      ]
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Customer-supplied metadata. Reserved internal keys may be stored for operations but are not echoed in public responses.",
      "example": {
        "external_ticket_id": "ticket_789",
        "channel": "crm"
      }
    }
  },
  "required": [
    "user"
  ]
}

curl -X POST "https://api.mortgageguidelines.com/v1/conversations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mgapi_live_your_key_here" \
  -H "Idempotency-Key: first-turn-user-123-001" \
  -d '{
  "title": "FHA gift funds",
  "user": {
    "external_user_id": "user_123",
    "email": "user@example.com",
    "name": "Test User"
  },
  "metadata": {
    "external_ticket_id": "ticket_789"
  }
}'

const response = await fetch("https://api.mortgageguidelines.com/v1/conversations", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer mgapi_live_your_key_here",
    "Idempotency-Key": "first-turn-user-123-001",
  },
  body: JSON.stringify({
  "title": "FHA gift funds",
  "user": {
    "external_user_id": "user_123",
    "email": "user@example.com",
    "name": "Test User"
  },
  "metadata": {
    "external_ticket_id": "ticket_789"
  }
}),
});

const data = await response.json();

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12"
}

Response bodies

201 response schema

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12"
}

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "conversation_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique conversation identifier returned by the API.",
      "example": "conv_3c2fd2bcf41f4f12"
    }
  },
  "required": [
    "request_id",
    "conversation_id"
  ]
}

400 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

409 response schema

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Scopes

chat:write

Headers

Authorization or X-API-Key
Idempotency-Key

Responses

201 Conversation created successfully.application/json
400 Invalid request body, invalid source selection, or unsupported streaming/idempotency combination.application/json
401 Missing, invalid, or inactive API key.application/json
403 The API key does not include the required scope for this operation.application/json
409 The request conflicts with current state, such as an idempotency-key conflict, immutable identity reassignment, duplicate or in-use team, or assignment to an archived team.application/json
429 The API key exceeded one of its configured rate limits.application/json
500 The service encountered an unexpected internal error. Retry with backoff and provide the returned request ID if the problem persists.application/json

get/v1/conversations/{conversationId}

Get a conversation

Returns the conversation metadata for a conversation owned by the authenticated API key.

Path and query parameters

conversationIdpathrequired

Conversation identifier returned by the API.

{
  "type": "string",
  "minLength": 1,
  "example": "conv_3c2fd2bcf41f4f12"
}

curl -X GET "https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12" \
  -H "Authorization: Bearer mgapi_live_your_key_here"

const response = await fetch("https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12", {
  headers: {
    Authorization: "Bearer mgapi_live_your_key_here",
  },
});

const data = await response.json();

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation": {
    "conversation_id": "conv_3c2fd2bcf41f4f12",
    "title": "FHA gift funds",
    "status": "active",
    "created_at": "2025-04-19T18:20:00.000Z",
    "updated_at": "2025-04-19T18:21:30.000Z",
    "message_count": 2,
    "metadata": {
      "external_ticket_id": "ticket_789"
    }
  }
}

Response bodies

200 response schema

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation": {
    "conversation_id": "conv_3c2fd2bcf41f4f12",
    "title": "FHA gift funds",
    "status": "active",
    "created_at": "2025-04-19T18:20:00.000Z",
    "updated_at": "2025-04-19T18:21:30.000Z",
    "message_count": 2,
    "metadata": {
      "external_ticket_id": "ticket_789"
    }
  }
}

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "conversation": {
      "type": "object",
      "properties": {
        "conversation_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique conversation identifier returned by the API.",
          "example": "conv_3c2fd2bcf41f4f12"
        },
        "title": {
          "type": [
            "string",
            "null"
          ],
          "example": "FHA gift funds"
        },
        "status": {
          "type": [
            "string",
            "null"
          ],
          "example": "active"
        },
        "created_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "Timestamp string returned by the backing data store.",
          "example": "2025-04-19T18:20:00.000Z"
        },
        "updated_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "Timestamp string returned by the backing data store.",
          "example": "2025-04-19T18:21:30.000Z"
        },
        "message_count": {
          "type": "integer",
          "minimum": 0,
          "example": 2
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {},
          "example": {
            "external_ticket_id": "ticket_789"
          }
        }
      },
      "required": [
        "conversation_id",
        "message_count",
        "metadata"
      ]
    }
  },
  "required": [
    "request_id",
    "conversation"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

404 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

get/v1/conversations/{conversationId}/messages

List messages in a conversation

Returns the stored messages for a conversation owned by the authenticated API key.

Path and query parameters

conversationIdpathrequired

Conversation identifier returned by the API.

{
  "type": "string",
  "minLength": 1,
  "example": "conv_3c2fd2bcf41f4f12"
}

curl -X GET "https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12/messages" \
  -H "Authorization: Bearer mgapi_live_your_key_here"

const response = await fetch("https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12/messages", {
  headers: {
    Authorization: "Bearer mgapi_live_your_key_here",
  },
});

const data = await response.json();

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12",
  "messages": [
    {
      "message_id": "msg_user_123",
      "role": "user",
      "content": "What are FHA gift fund rules?",
      "citations": [],
      "sources": [],
      "metadata": {
        "channel": "crm"
      },
      "created_at": "2025-04-19T18:20:00.000Z"
    },
    {
      "message_id": "msg_1fecc99b7f334e6c",
      "role": "assistant",
      "content": "Gift funds are generally allowed with documentation.",
      "citations": [
        {
          "documentTitle": "Fannie Mae Selling Guide",
          "section": "B3-4.3-04",
          "url": "https://selling-guide.fanniemae.com/",
          "pageNumber": 12
        }
      ],
      "sources": [
        {
          "url": "https://selling-guide.fanniemae.com/",
          "title": "Fannie Mae Selling Guide",
          "description": "Document from selling-guide.fanniemae.com",
          "citationCount": 1
        }
      ],
      "metadata": {
        "tokens_used": 123
      },
      "created_at": "2025-04-19T18:21:30.000Z"
    }
  ]
}

Response bodies

200 response schema

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12",
  "messages": [
    {
      "message_id": "msg_user_123",
      "role": "user",
      "content": "What are FHA gift fund rules?",
      "citations": [],
      "sources": [],
      "metadata": {
        "channel": "crm"
      },
      "created_at": "2025-04-19T18:20:00.000Z"
    },
    {
      "message_id": "msg_1fecc99b7f334e6c",
      "role": "assistant",
      "content": "Gift funds are generally allowed with documentation.",
      "citations": [
        {
          "documentTitle": "Fannie Mae Selling Guide",
          "section": "B3-4.3-04",
          "url": "https://selling-guide.fanniemae.com/",
          "pageNumber": 12
        }
      ],
      "sources": [
        {
          "url": "https://selling-guide.fanniemae.com/",
          "title": "Fannie Mae Selling Guide",
          "description": "Document from selling-guide.fanniemae.com",
          "citationCount": 1
        }
      ],
      "metadata": {
        "tokens_used": 123
      },
      "created_at": "2025-04-19T18:21:30.000Z"
    }
  ]
}

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "conversation_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique conversation identifier returned by the API.",
      "example": "conv_3c2fd2bcf41f4f12"
    },
    "messages": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "message_id": {
            "type": "string",
            "minLength": 1,
            "description": "Unique message identifier returned by the API.",
            "example": "msg_1fecc99b7f334e6c"
          },
          "role": {
            "type": [
              "string",
              "null"
            ],
            "example": "assistant"
          },
          "content": {
            "type": [
              "string",
              "null"
            ],
            "example": "Gift funds are generally allowed with documentation."
          },
          "citations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "documentTitle": {
                  "type": "string",
                  "example": "Fannie Mae Selling Guide"
                },
                "section": {
                  "type": "string",
                  "example": "B3-4.3-04"
                },
                "subsection": {
                  "type": "string",
                  "example": "Personal Gifts"
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "example": "https://selling-guide.fanniemae.com/"
                },
                "pdfUrl": {
                  "type": "string",
                  "format": "uri",
                  "example": "https://selling-guide.fanniemae.com/guide.pdf"
                },
                "pageNumber": {
                  "type": "integer",
                  "exclusiveMinimum": 0,
                  "example": 12
                },
                "pageRangeStart": {
                  "type": "integer",
                  "exclusiveMinimum": 0,
                  "example": 12
                },
                "pageRangeEnd": {
                  "type": "integer",
                  "exclusiveMinimum": 0,
                  "example": 13
                },
                "pageRangeLabel": {
                  "type": "string",
                  "example": "12-13"
                },
                "tenantSourceKey": {
                  "type": "string",
                  "example": "product-guides"
                },
                "tenantSourceLabel": {
                  "type": "string",
                  "example": "Product Guides"
                }
              },
              "additionalProperties": false,
              "description": "Sanitized citation fields for display and source navigation."
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri",
                  "example": "https://selling-guide.fanniemae.com/"
                },
                "title": {
                  "type": "string",
                  "example": "Fannie Mae Selling Guide"
                },
                "description": {
                  "type": "string",
                  "example": "Document from selling-guide.fanniemae.com"
                },
                "citationCount": {
                  "type": "integer",
                  "minimum": 0,
                  "example": 1
                },
                "tenantSourceKey": {
                  "type": "string",
                  "example": "product-guides"
                },
                "tenantSourceLabel": {
                  "type": "string",
                  "example": "Product Guides"
                }
              },
              "additionalProperties": false,
              "description": "Sanitized source summary fields for display and source navigation."
            }
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {},
            "description": "Customer-supplied metadata. Reserved internal keys may be stored for operations but are not echoed in public responses.",
            "example": {
              "external_ticket_id": "ticket_789",
              "channel": "crm"
            }
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "Timestamp string returned by the backing data store.",
            "example": "2025-04-19T18:21:30.000Z"
          }
        },
        "required": [
          "message_id",
          "citations",
          "sources",
          "metadata"
        ]
      }
    }
  },
  "required": [
    "request_id",
    "conversation_id",
    "messages"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

404 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Messages

2 endpoints

post/v1/messages

Send a message and optionally create the conversation

Creates the conversation when `conversation_id` is omitted, sends the user message, and returns the assistant response.

Idempotency

`Idempotency-Key` is supported only for non-streaming requests.
Reusing the same key with a different request body returns `409 idempotency_conflict`.

Streaming

When `stream: true`, the response content type becomes `text/event-stream`.
The first event is `public_api_conversation`, followed by sanitized token, citation, source, and completion events, and then `public_api_complete`.
Streaming metadata contains only `tokens_used`.

Request body

First-message payload. Supply `conversation_id` to continue an existing conversation or omit it to create one automatically.

{
  "message": "What are FHA gift fund rules?",
  "user": {
    "external_user_id": "user_123",
    "email": "user@example.com",
    "name": "Test User"
  },
  "conversation": {
    "title": "FHA gift funds",
    "metadata": {
      "external_ticket_id": "ticket_789"
    }
  },
  "metadata": {
    "channel": "crm"
  }
}

{
  "allOf": [
    {
      "type": "object",
      "properties": {
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4000,
          "description": "Prompt or question to send to the assistant.",
          "example": "What documentation is required?"
        },
        "user": {
          "type": "object",
          "properties": {
            "external_user_id": {
              "type": "string",
              "minLength": 1,
              "description": "Stable identifier from your system for the end user.",
              "example": "user_123"
            },
            "email": {
              "type": "string",
              "format": "email",
              "description": "Optional email address for the external user.",
              "example": "user@example.com"
            },
            "name": {
              "type": "string",
              "description": "Optional display name for the external user.",
              "example": "Test User"
            }
          },
          "required": [
            "external_user_id"
          ]
        },
        "stream": {
          "type": "boolean",
          "description": "Set to true to receive a text/event-stream response.",
          "example": false
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {},
          "description": "Customer-supplied metadata. Reserved internal keys may be stored for operations but are not echoed in public responses.",
          "example": {
            "external_ticket_id": "ticket_789",
            "channel": "crm"
          }
        },
        "search_options": {
          "type": "object",
          "properties": {
            "agency_source_types": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Subset of agency sources to include in this request.",
              "example": [
                "fha",
                "va"
              ]
            },
            "tenant_source_keys": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Subset of tenant bucket sources to include in this request.",
              "example": [
                "product-guides"
              ]
            },
            "shared_source_types": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Subset of shared source types to include in this request.",
              "example": [
                "mortgage_guidelines"
              ]
            }
          }
        }
      },
      "required": [
        "message",
        "user"
      ]
    },
    {
      "type": "object",
      "properties": {
        "conversation_id": {
          "type": "string",
          "minLength": 1,
          "description": "Existing conversation identifier. Omit this to let the API create a new conversation.",
          "example": "conv_3c2fd2bcf41f4f12"
        },
        "conversation": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "description": "Optional conversation title used when the API creates a new conversation.",
              "example": "FHA gift funds"
            },
            "metadata": {
              "type": "object",
              "additionalProperties": {},
              "description": "Customer-supplied metadata. Reserved internal keys may be stored for operations but are not echoed in public responses.",
              "example": {
                "external_ticket_id": "ticket_789",
                "channel": "crm"
              }
            }
          }
        }
      }
    }
  ]
}

curl -X POST "https://api.mortgageguidelines.com/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mgapi_live_your_key_here" \
  -H "Idempotency-Key: first-turn-user-123-001" \
  -d '{
  "message": "What are FHA gift fund rules?",
  "user": {
    "external_user_id": "user_123",
    "email": "user@example.com",
    "name": "Test User"
  },
  "conversation": {
    "title": "FHA gift funds",
    "metadata": {
      "external_ticket_id": "ticket_789"
    }
  },
  "metadata": {
    "channel": "crm"
  }
}'

const response = await fetch("https://api.mortgageguidelines.com/v1/messages", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer mgapi_live_your_key_here",
    "Idempotency-Key": "first-turn-user-123-001",
  },
  body: JSON.stringify({
  "message": "What are FHA gift fund rules?",
  "user": {
    "external_user_id": "user_123",
    "email": "user@example.com",
    "name": "Test User"
  },
  "conversation": {
    "title": "FHA gift funds",
    "metadata": {
      "external_ticket_id": "ticket_789"
    }
  },
  "metadata": {
    "channel": "crm"
  }
}),
});

const data = await response.json();

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12",
  "conversation_created": true,
  "message_id": "msg_1fecc99b7f334e6c",
  "response": "Gift funds are generally allowed with documentation.",
  "citations": [
    {
      "documentTitle": "Fannie Mae Selling Guide",
      "section": "B3-4.3-04",
      "url": "https://selling-guide.fanniemae.com/",
      "pageNumber": 12
    }
  ],
  "sources": [
    {
      "url": "https://selling-guide.fanniemae.com/",
      "title": "Fannie Mae Selling Guide",
      "description": "Document from selling-guide.fanniemae.com",
      "citationCount": 1
    }
  ],
  "metadata": {
    "tokens_used": 123
  }
}

data: {"type":"public_api_conversation","request_id":"req_9b8f0b5fcb5b4eaa","conversation_id":"conv_3c2fd2bcf41f4f12","conversation_created":true}

data: {"type":"content","content":"Gift funds are generally allowed with "}

data: {"type":"content_postprocessed","content":"Gift funds are generally allowed with documentation."}

data: {"type":"complete","metadata":{"tokens_used":123}}

data: {"type":"public_api_complete","request_id":"req_9b8f0b5fcb5b4eaa","conversation_id":"conv_3c2fd2bcf41f4f12","message_id":"msg_1fecc99b7f334e6c"}

Response bodies

200 response schema

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12",
  "conversation_created": true,
  "message_id": "msg_1fecc99b7f334e6c",
  "response": "Gift funds are generally allowed with documentation.",
  "citations": [
    {
      "documentTitle": "Fannie Mae Selling Guide",
      "section": "B3-4.3-04",
      "url": "https://selling-guide.fanniemae.com/",
      "pageNumber": 12
    }
  ],
  "sources": [
    {
      "url": "https://selling-guide.fanniemae.com/",
      "title": "Fannie Mae Selling Guide",
      "description": "Document from selling-guide.fanniemae.com",
      "citationCount": 1
    }
  ],
  "metadata": {
    "tokens_used": 123
  }
}

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "conversation_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique conversation identifier returned by the API.",
      "example": "conv_3c2fd2bcf41f4f12"
    },
    "conversation_created": {
      "type": "boolean",
      "description": "Present only on POST /v1/messages. Indicates whether the API created the conversation during this request.",
      "example": true
    },
    "message_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique message identifier returned by the API.",
      "example": "msg_1fecc99b7f334e6c"
    },
    "response": {
      "type": "string",
      "example": "Gift funds are generally allowed with documentation."
    },
    "citations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "documentTitle": {
            "type": "string",
            "example": "Fannie Mae Selling Guide"
          },
          "section": {
            "type": "string",
            "example": "B3-4.3-04"
          },
          "subsection": {
            "type": "string",
            "example": "Personal Gifts"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://selling-guide.fanniemae.com/"
          },
          "pdfUrl": {
            "type": "string",
            "format": "uri",
            "example": "https://selling-guide.fanniemae.com/guide.pdf"
          },
          "pageNumber": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "example": 12
          },
          "pageRangeStart": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "example": 12
          },
          "pageRangeEnd": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "example": 13
          },
          "pageRangeLabel": {
            "type": "string",
            "example": "12-13"
          },
          "tenantSourceKey": {
            "type": "string",
            "example": "product-guides"
          },
          "tenantSourceLabel": {
            "type": "string",
            "example": "Product Guides"
          }
        },
        "additionalProperties": false,
        "description": "Sanitized citation fields for display and source navigation."
      }
    },
    "sources": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://selling-guide.fanniemae.com/"
          },
          "title": {
            "type": "string",
            "example": "Fannie Mae Selling Guide"
          },
          "description": {
            "type": "string",
            "example": "Document from selling-guide.fanniemae.com"
          },
          "citationCount": {
            "type": "integer",
            "minimum": 0,
            "example": 1
          },
          "tenantSourceKey": {
            "type": "string",
            "example": "product-guides"
          },
          "tenantSourceLabel": {
            "type": "string",
            "example": "Product Guides"
          }
        },
        "additionalProperties": false,
        "description": "Sanitized source summary fields for display and source navigation."
      }
    },
    "metadata": {
      "type": "object",
      "properties": {
        "tokens_used": {
          "type": "integer",
          "minimum": 0,
          "description": "Total tokens recorded for the completion.",
          "example": 123
        }
      },
      "required": [
        "tokens_used"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "conversation_id",
    "message_id",
    "response",
    "citations",
    "sources",
    "metadata"
  ]
}

400 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

404 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

409 response schema

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

502 response schema

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Scopes

chat:write

Headers

Authorization or X-API-Key
Idempotency-Key

Responses

200 Non-streaming assistant response.application/json, text/event-stream
400 Invalid request body, invalid source selection, or unsupported streaming/idempotency combination.application/json
401 Missing, invalid, or inactive API key.application/json
403 The API key does not include the required scope for this operation.application/json
404 The requested resource was not found or is not visible to the authenticated API key.application/json
409 The request conflicts with current state, such as an idempotency-key conflict, immutable identity reassignment, duplicate or in-use team, or assignment to an archived team.application/json
429 The API key exceeded one of its configured rate limits.application/json
500 The service encountered an unexpected internal error. Retry with backoff and provide the returned request ID if the problem persists.application/json
502 The upstream chat service failed or returned an unexpected response.application/json

post/v1/conversations/{conversationId}/messages

Send a message to an existing conversation

Sends a user message to an existing conversation and returns the assistant response.

Idempotency

`Idempotency-Key` is supported only for non-streaming requests.
Matching retries replay the stored JSON response snapshot.

Streaming

When `stream: true`, the response content type becomes `text/event-stream`.
Existing-conversation streams omit the leading `public_api_conversation` event and always finish with `public_api_complete`.
Streaming metadata contains only `tokens_used`.

Path and query parameters

conversationIdpathrequired

Conversation identifier returned by the API.

{
  "type": "string",
  "minLength": 1,
  "example": "conv_3c2fd2bcf41f4f12"
}

Request body

Message payload for an existing conversation.

{
  "message": "What documentation is required?",
  "user": {
    "external_user_id": "user_123"
  }
}

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "Prompt or question to send to the assistant.",
      "example": "What documentation is required?"
    },
    "user": {
      "type": "object",
      "properties": {
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "description": "Stable identifier from your system for the end user.",
          "example": "user_123"
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Optional email address for the external user.",
          "example": "user@example.com"
        },
        "name": {
          "type": "string",
          "description": "Optional display name for the external user.",
          "example": "Test User"
        }
      },
      "required": [
        "external_user_id"
      ]
    },
    "stream": {
      "type": "boolean",
      "description": "Set to true to receive a text/event-stream response.",
      "example": false
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Customer-supplied metadata. Reserved internal keys may be stored for operations but are not echoed in public responses.",
      "example": {
        "external_ticket_id": "ticket_789",
        "channel": "crm"
      }
    },
    "search_options": {
      "type": "object",
      "properties": {
        "agency_source_types": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Subset of agency sources to include in this request.",
          "example": [
            "fha",
            "va"
          ]
        },
        "tenant_source_keys": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Subset of tenant bucket sources to include in this request.",
          "example": [
            "product-guides"
          ]
        },
        "shared_source_types": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Subset of shared source types to include in this request.",
          "example": [
            "mortgage_guidelines"
          ]
        }
      }
    }
  },
  "required": [
    "message",
    "user"
  ]
}

curl -X POST "https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12/messages" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mgapi_live_your_key_here" \
  -H "Idempotency-Key: follow-up-user-123-001" \
  -d '{
  "message": "What documentation is required?",
  "user": {
    "external_user_id": "user_123"
  }
}'

const response = await fetch("https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12/messages", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "mgapi_live_your_key_here",
    "Idempotency-Key": "follow-up-user-123-001",
  },
  body: JSON.stringify({
    message: "What documentation is required?",
    user: {
      external_user_id: "user_123",
    },
  }),
});

const data = await response.json();

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12",
  "message_id": "msg_1fecc99b7f334e6c",
  "response": "Gift funds are generally allowed with documentation.",
  "citations": [
    {
      "documentTitle": "Fannie Mae Selling Guide",
      "section": "B3-4.3-04",
      "url": "https://selling-guide.fanniemae.com/",
      "pageNumber": 12
    }
  ],
  "sources": [
    {
      "url": "https://selling-guide.fanniemae.com/",
      "title": "Fannie Mae Selling Guide",
      "description": "Document from selling-guide.fanniemae.com",
      "citationCount": 1
    }
  ],
  "metadata": {
    "tokens_used": 123
  }
}

data: {"type":"content","content":"The conversation can continue using the existing ID."}

data: {"type":"complete","metadata":{"tokens_used":88}}

data: {"type":"public_api_complete","request_id":"req_9b8f0b5fcb5b4eaa","conversation_id":"conv_3c2fd2bcf41f4f12","message_id":"msg_1fecc99b7f334e6c"}

Response bodies

200 response schema

{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12",
  "message_id": "msg_1fecc99b7f334e6c",
  "response": "Gift funds are generally allowed with documentation.",
  "citations": [
    {
      "documentTitle": "Fannie Mae Selling Guide",
      "section": "B3-4.3-04",
      "url": "https://selling-guide.fanniemae.com/",
      "pageNumber": 12
    }
  ],
  "sources": [
    {
      "url": "https://selling-guide.fanniemae.com/",
      "title": "Fannie Mae Selling Guide",
      "description": "Document from selling-guide.fanniemae.com",
      "citationCount": 1
    }
  ],
  "metadata": {
    "tokens_used": 123
  }
}

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "conversation_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique conversation identifier returned by the API.",
      "example": "conv_3c2fd2bcf41f4f12"
    },
    "conversation_created": {
      "type": "boolean",
      "description": "Present only on POST /v1/messages. Indicates whether the API created the conversation during this request.",
      "example": true
    },
    "message_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique message identifier returned by the API.",
      "example": "msg_1fecc99b7f334e6c"
    },
    "response": {
      "type": "string",
      "example": "Gift funds are generally allowed with documentation."
    },
    "citations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "documentTitle": {
            "type": "string",
            "example": "Fannie Mae Selling Guide"
          },
          "section": {
            "type": "string",
            "example": "B3-4.3-04"
          },
          "subsection": {
            "type": "string",
            "example": "Personal Gifts"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://selling-guide.fanniemae.com/"
          },
          "pdfUrl": {
            "type": "string",
            "format": "uri",
            "example": "https://selling-guide.fanniemae.com/guide.pdf"
          },
          "pageNumber": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "example": 12
          },
          "pageRangeStart": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "example": 12
          },
          "pageRangeEnd": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "example": 13
          },
          "pageRangeLabel": {
            "type": "string",
            "example": "12-13"
          },
          "tenantSourceKey": {
            "type": "string",
            "example": "product-guides"
          },
          "tenantSourceLabel": {
            "type": "string",
            "example": "Product Guides"
          }
        },
        "additionalProperties": false,
        "description": "Sanitized citation fields for display and source navigation."
      }
    },
    "sources": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://selling-guide.fanniemae.com/"
          },
          "title": {
            "type": "string",
            "example": "Fannie Mae Selling Guide"
          },
          "description": {
            "type": "string",
            "example": "Document from selling-guide.fanniemae.com"
          },
          "citationCount": {
            "type": "integer",
            "minimum": 0,
            "example": 1
          },
          "tenantSourceKey": {
            "type": "string",
            "example": "product-guides"
          },
          "tenantSourceLabel": {
            "type": "string",
            "example": "Product Guides"
          }
        },
        "additionalProperties": false,
        "description": "Sanitized source summary fields for display and source navigation."
      }
    },
    "metadata": {
      "type": "object",
      "properties": {
        "tokens_used": {
          "type": "integer",
          "minimum": 0,
          "description": "Total tokens recorded for the completion.",
          "example": 123
        }
      },
      "required": [
        "tokens_used"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "conversation_id",
    "message_id",
    "response",
    "citations",
    "sources",
    "metadata"
  ]
}

400 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

404 response schema

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

409 response schema

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 response schema

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 response schema

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

502 response schema

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Scopes

chat:write

Headers

Authorization or X-API-Key
Idempotency-Key

Responses

200 Non-streaming assistant response.application/json, text/event-stream
400 Invalid request body, invalid source selection, or unsupported streaming/idempotency combination.application/json
401 Missing, invalid, or inactive API key.application/json
403 The API key does not include the required scope for this operation.application/json
404 The requested resource was not found or is not visible to the authenticated API key.application/json
409 The request conflicts with current state, such as an idempotency-key conflict, immutable identity reassignment, duplicate or in-use team, or assignment to an archived team.application/json
429 The API key exceeded one of its configured rate limits.application/json
500 The service encountered an unexpected internal error. Retry with backoff and provide the returned request ID if the problem persists.application/json
502 The upstream chat service failed or returned an unexpected response.application/json