Customer Planned contract

Create a customer-controlled connection intent

Accepts verified correlation claims for an external account and always returns the same 202 shape for zero, one, or multiple private candidates. Matching never authorizes access; no candidate, masked contact, customer identifier, existence signal, or out-of-band candidate notification is returned or triggered.

Runtime status: unavailable. This is a source contract, not a live access or availability guarantee. Learn more

POST/partner/customer-connections/v1/connection-intents

Authority

Profile: partner
Data class: customer_personal
Required operation: createPartnerCustomerConnectionIntent
Subject scopes: No subject scopes declared for this operation.

partnerServiceBearer security scheme

{
  "type": "http",
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "description": "Short-lived, server-only partner credential used for capabilities, intent creation, and token exchange. Purpose \"partner-customer-connections\", audience \"partner-customer-connections-service\", and operation scope \"customer-connections:partner:<operationId>\" are exact validation inputs. Claims: assignmentId, aud, exp, iat, iss, jti, operation, partnerId, purpose, sub, tenantId, tokenUse. It reaches no customer data on its own."
}

Request

Request parameters
Parameter	Location	Requirement	Schema
`smokestack-api-version`	header	Required	`{"type":"string","const":"2026-08-24"}`
`x-request-id`	header	Optional	`{"type":"string","minLength":1,"maxLength":200}`
`x-correlation-id`	header	Optional	`{"type":"string","minLength":1,"maxLength":200}`
`idempotency-key`	header	Required	`{"type":"string","minLength":16,"maxLength":200}`

Request body

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerConnectionIntentRequest"
      }
    }
  }
}

Idempotency

{
  "required": true,
  "retentionSeconds": 604800,
  "replay": "same scoped key and canonical payload returns the stored business status and payload",
  "conflict": "same scoped key with a different canonical payload returns idempotency_conflict"
}

Request examples

Templates for your server, not browser code. Replace every placeholder and use your approved origin. For requests with a body, construct request.json / requestBody / request_body from the schema.

Language

# Replace placeholders using your approved server-side integration.
curl --request POST 'https://partner-api.invalid/partner/customer-connections/v1/connection-intents' \
  --header 'smokestack-api-version: 2026-08-24' \
  --header 'idempotency-key: <IDEMPOTENCY_KEY>' \
  --header 'Authorization: Bearer <SERVER_ONLY_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data @request.json

Responses

202 Accepted without disclosing customer-match state.

{
  "description": "Accepted without disclosing customer-match state.",
  "headers": {
    "SMOKESTACK-API-Version": {
      "description": "The negotiated compatible contract revision.",
      "schema": {
        "type": "string",
        "const": "2026-08-24"
      }
    },
    "X-Request-ID": {
      "description": "The request identifier accepted from the caller or generated by SMOKESTACK.",
      "schema": {
        "type": "string"
      }
    },
    "X-Correlation-ID": {
      "description": "The end-to-end correlation identifier.",
      "schema": {
        "type": "string"
      }
    },
    "Deprecation": {
      "description": "RFC 9745 Structured Field Date when an operation or revision is deprecated.",
      "schema": {
        "type": "string"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerConnectionIntentResponse"
      }
    }
  }
}

400 Invalid request syntax. Private customer-matching outcomes never use this response for connection-intent creation.

{
  "description": "Invalid request syntax. Private customer-matching outcomes never use this response for connection-intent creation.",
  "headers": {
    "SMOKESTACK-API-Version": {
      "description": "The negotiated compatible contract revision.",
      "schema": {
        "type": "string",
        "const": "2026-08-24"
      }
    },
    "X-Request-ID": {
      "description": "The request identifier accepted from the caller or generated by SMOKESTACK.",
      "schema": {
        "type": "string"
      }
    },
    "X-Correlation-ID": {
      "description": "The end-to-end correlation identifier.",
      "schema": {
        "type": "string"
      }
    },
    "Deprecation": {
      "description": "RFC 9745 Structured Field Date when an operation or revision is deprecated.",
      "schema": {
        "type": "string"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerError"
      }
    }
  }
}

401 The required partner or subject credential is missing or invalid.

{
  "description": "The required partner or subject credential is missing or invalid.",
  "headers": {
    "SMOKESTACK-API-Version": {
      "description": "The negotiated compatible contract revision.",
      "schema": {
        "type": "string",
        "const": "2026-08-24"
      }
    },
    "X-Request-ID": {
      "description": "The request identifier accepted from the caller or generated by SMOKESTACK.",
      "schema": {
        "type": "string"
      }
    },
    "X-Correlation-ID": {
      "description": "The end-to-end correlation identifier.",
      "schema": {
        "type": "string"
      }
    },
    "Deprecation": {
      "description": "RFC 9745 Structured Field Date when an operation or revision is deprecated.",
      "schema": {
        "type": "string"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerError"
      }
    }
  }
}

403 The partner credential lacks authority for this operation; no customer or match state is disclosed.

{
  "description": "The partner credential lacks authority for this operation; no customer or match state is disclosed.",
  "headers": {
    "SMOKESTACK-API-Version": {
      "description": "The negotiated compatible contract revision.",
      "schema": {
        "type": "string",
        "const": "2026-08-24"
      }
    },
    "X-Request-ID": {
      "description": "The request identifier accepted from the caller or generated by SMOKESTACK.",
      "schema": {
        "type": "string"
      }
    },
    "X-Correlation-ID": {
      "description": "The end-to-end correlation identifier.",
      "schema": {
        "type": "string"
      }
    },
    "Deprecation": {
      "description": "RFC 9745 Structured Field Date when an operation or revision is deprecated.",
      "schema": {
        "type": "string"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerError"
      }
    }
  }
}

406 The requested contract revision is unsupported.

{
  "description": "The requested contract revision is unsupported.",
  "headers": {
    "SMOKESTACK-API-Version": {
      "description": "The negotiated compatible contract revision.",
      "schema": {
        "type": "string",
        "const": "2026-08-24"
      }
    },
    "X-Request-ID": {
      "description": "The request identifier accepted from the caller or generated by SMOKESTACK.",
      "schema": {
        "type": "string"
      }
    },
    "X-Correlation-ID": {
      "description": "The end-to-end correlation identifier.",
      "schema": {
        "type": "string"
      }
    },
    "Deprecation": {
      "description": "RFC 9745 Structured Field Date when an operation or revision is deprecated.",
      "schema": {
        "type": "string"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerError"
      }
    }
  }
}

409 The idempotency key was reused with a different canonical payload.

{
  "description": "The idempotency key was reused with a different canonical payload.",
  "headers": {
    "SMOKESTACK-API-Version": {
      "description": "The negotiated compatible contract revision.",
      "schema": {
        "type": "string",
        "const": "2026-08-24"
      }
    },
    "X-Request-ID": {
      "description": "The request identifier accepted from the caller or generated by SMOKESTACK.",
      "schema": {
        "type": "string"
      }
    },
    "X-Correlation-ID": {
      "description": "The end-to-end correlation identifier.",
      "schema": {
        "type": "string"
      }
    },
    "Deprecation": {
      "description": "RFC 9745 Structured Field Date when an operation or revision is deprecated.",
      "schema": {
        "type": "string"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerError"
      }
    }
  }
}

429 Partner, external-subject, intent, or pairwise-subject rate limit exceeded.

{
  "description": "Partner, external-subject, intent, or pairwise-subject rate limit exceeded.",
  "headers": {
    "SMOKESTACK-API-Version": {
      "description": "The negotiated compatible contract revision.",
      "schema": {
        "type": "string",
        "const": "2026-08-24"
      }
    },
    "X-Request-ID": {
      "description": "The request identifier accepted from the caller or generated by SMOKESTACK.",
      "schema": {
        "type": "string"
      }
    },
    "X-Correlation-ID": {
      "description": "The end-to-end correlation identifier.",
      "schema": {
        "type": "string"
      }
    },
    "Deprecation": {
      "description": "RFC 9745 Structured Field Date when an operation or revision is deprecated.",
      "schema": {
        "type": "string"
      }
    },
    "Retry-After": {
      "schema": {
        "type": "integer",
        "minimum": 0
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerError"
      }
    }
  }
}

500 Unexpected error without customer or match details.

{
  "description": "Unexpected error without customer or match details.",
  "headers": {
    "SMOKESTACK-API-Version": {
      "description": "The negotiated compatible contract revision.",
      "schema": {
        "type": "string",
        "const": "2026-08-24"
      }
    },
    "X-Request-ID": {
      "description": "The request identifier accepted from the caller or generated by SMOKESTACK.",
      "schema": {
        "type": "string"
      }
    },
    "X-Correlation-ID": {
      "description": "The end-to-end correlation identifier.",
      "schema": {
        "type": "string"
      }
    },
    "Deprecation": {
      "description": "RFC 9745 Structured Field Date when an operation or revision is deprecated.",
      "schema": {
        "type": "string"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerError"
      }
    }
  }
}

503 An authoritative dependency is unavailable; the service does not guess.

{
  "description": "An authoritative dependency is unavailable; the service does not guess.",
  "headers": {
    "SMOKESTACK-API-Version": {
      "description": "The negotiated compatible contract revision.",
      "schema": {
        "type": "string",
        "const": "2026-08-24"
      }
    },
    "X-Request-ID": {
      "description": "The request identifier accepted from the caller or generated by SMOKESTACK.",
      "schema": {
        "type": "string"
      }
    },
    "X-Correlation-ID": {
      "description": "The end-to-end correlation identifier.",
      "schema": {
        "type": "string"
      }
    },
    "Deprecation": {
      "description": "RFC 9745 Structured Field Date when an operation or revision is deprecated.",
      "schema": {
        "type": "string"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerError"
      }
    }
  }
}

Referenced schemas

Only schemas reachable from this operation are shown. The revision-pinned OpenAPI download includes their complete definitions.

PartnerCustomerConnectionIntentRequest

{
  "type": "object",
  "properties": {
    "externalSubject": {
      "type": "string",
      "pattern": "^ext_[A-Za-z0-9_-]{16,120}$"
    },
    "purpose": {
      "type": "string",
      "enum": [
        "CUSTOMER_ACCOUNT_CONNECTION"
      ]
    },
    "requestedScopes": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "customer.profile.basic",
          "customer.profile.contact",
          "customer.profile.birth_date",
          "customer.medical_eligibility.read"
        ]
      },
      "minItems": 1,
      "maxItems": 4
    },
    "redirectUri": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri"
    },
    "state": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._~-]{16,512}$"
    },
    "codeChallenge": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{43,128}$"
    },
    "codeChallengeMethod": {
      "type": "string",
      "enum": [
        "S256"
      ]
    },
    "correlationClaims": {
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "EMAIL"
                ]
              },
              "value": {
                "type": "string",
                "maxLength": 320,
                "format": "email"
              },
              "verifiedAt": {
                "type": "string",
                "format": "date-time"
              },
              "verificationMethod": {
                "type": "string",
                "enum": [
                  "EMAIL_OTP",
                  "IN_PERSON",
                  "ACCOUNT_RECORD"
                ]
              }
            },
            "required": [
              "kind",
              "value",
              "verifiedAt",
              "verificationMethod"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "PHONE"
                ]
              },
              "value": {
                "type": "string",
                "pattern": "^\\+[1-9]\\d{7,14}$"
              },
              "verifiedAt": {
                "type": "string",
                "format": "date-time"
              },
              "verificationMethod": {
                "type": "string",
                "enum": [
                  "SMS_OTP",
                  "IN_PERSON",
                  "ACCOUNT_RECORD"
                ]
              }
            },
            "required": [
              "kind",
              "value",
              "verifiedAt",
              "verificationMethod"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "LEGAL_NAME"
                ]
              },
              "givenName": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "familyName": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "verifiedAt": {
                "type": "string",
                "format": "date-time"
              },
              "verificationMethod": {
                "type": "string",
                "enum": [
                  "GOVERNMENT_ID",
                  "IN_PERSON",
                  "ACCOUNT_RECORD"
                ]
              }
            },
            "required": [
              "kind",
              "givenName",
              "familyName",
              "verifiedAt",
              "verificationMethod"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "DATE_OF_BIRTH"
                ]
              },
              "value": {
                "type": "string",
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
              },
              "verifiedAt": {
                "type": "string",
                "format": "date-time"
              },
              "verificationMethod": {
                "type": "string",
                "enum": [
                  "GOVERNMENT_ID",
                  "IN_PERSON",
                  "ACCOUNT_RECORD"
                ]
              }
            },
            "required": [
              "kind",
              "value",
              "verifiedAt",
              "verificationMethod"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "POSTAL_ADDRESS"
                ]
              },
              "postalCode": {
                "type": "string",
                "minLength": 3,
                "maxLength": 20
              },
              "countryCode": {
                "type": "string",
                "pattern": "^[A-Z]{2}$"
              },
              "verifiedAt": {
                "type": "string",
                "format": "date-time"
              },
              "verificationMethod": {
                "type": "string",
                "enum": [
                  "GOVERNMENT_ID",
                  "IN_PERSON",
                  "ACCOUNT_RECORD"
                ]
              }
            },
            "required": [
              "kind",
              "postalCode",
              "countryCode",
              "verifiedAt",
              "verificationMethod"
            ],
            "additionalProperties": false
          }
        ]
      },
      "minItems": 3,
      "maxItems": 5
    }
  },
  "required": [
    "externalSubject",
    "purpose",
    "requestedScopes",
    "redirectUri",
    "state",
    "codeChallenge",
    "codeChallengeMethod",
    "correlationClaims"
  ],
  "additionalProperties": false
}

PartnerCustomerConnectionIntentResponse

{
  "type": "object",
  "properties": {
    "connectionIntentId": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "string",
      "enum": [
        "AWAITING_CUSTOMER_AUTHORIZATION"
      ]
    },
    "authorizationUrl": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time"
    },
    "meta": {
      "type": "object",
      "properties": {
        "apiVersion": {
          "type": "string",
          "enum": [
            "2026-08-24"
          ]
        },
        "requestId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "generatedAt": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "apiVersion",
        "requestId",
        "generatedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "connectionIntentId",
    "status",
    "authorizationUrl",
    "expiresAt",
    "meta"
  ],
  "additionalProperties": false
}

PartnerCustomerError

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "invalid_request",
        "authentication_required",
        "permission_denied",
        "api_version_not_supported",
        "invalid_grant",
        "idempotency_conflict",
        "rate_limited",
        "dependency_unavailable",
        "internal_error"
      ]
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Public, non-diagnostic message. invalid_grant must never describe customer or match state."
    },
    "requestId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "retryable": {
      "type": "boolean"
    }
  },
  "required": [
    "code",
    "message",
    "requestId",
    "retryable"
  ],
  "additionalProperties": false
}

← All Customer Connections API operations