Verify contact

Create and validate a new payout recipient, returning the contactId, purposeId, and refId needed to submit the payout. Creditor name, street, city, and country must use Latin characters.

post

/api/fma/v1/verify-contact

Authorizations

X-Api-SignaturestringRequired

Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide.

Header parameters

X-Api-SignaturestringRequired

0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide.

X-Api-DeadlinestringRequired

Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes.

X-Api-PublicKeystringRequired

0x-prefixed partner signer address registered with UR.

X-Ur-IdstringOptional

Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first.

X-External-User-IdstringOptional

Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first.

Body

accountstringRequired

Recipient IBAN or account number.

bankNamestringRequired

Recipient bank name.

bicstringRequired

Recipient bank BIC.

purposeintegerRequired

Payment purpose ID from the payment purposes list.

referencestringRequired

Payment reference.

Responses

200

Standard envelope. Business errors return HTTP 200 with a non-zero code.

application/json

Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.

codeintegerRequired

0 on success; non-zero business error code.

messagestringRequired

Human-readable explanation. May be empty on success.

post/api/fma/v1/verify-contact

POST /api/fma/v1/verify-contact HTTP/1.1
Host: openapi.ur.app
X-Api-Signature: text
X-Api-Deadline: text
X-Api-PublicKey: text
Content-Type: application/json
Accept: */*
Content-Length: 247

{
  "account": "CH93 0076 2011 6238 5295 7",
  "bankName": "Hypothekarbank Lenzburg AG",
  "bic": "HYPCH22",
  "purpose": 1,
  "reference": "Invoice 2026-001",
  "creditorInfo": {
    "name": "Alice Doe",
    "street": "Bahnhofstrasse 1",
    "city": "Zurich",
    "zip": "8001",
    "country": "CH"
  }
}

200

Standard envelope. Business errors return HTTP 200 with a non-zero code.

{
  "code": 0,
  "message": "",
  "data": {
    "account": "CH93 0076 2011 6238 5295 7",
    "bankName": "Hypothekarbank Lenzburg AG",
    "bic": "HYPCH22",
    "purpose": 1,
    "reference": "...",
    "clientPayoutRefParams": {
      "contactId": "SP",
      "purposeId": 1,
      "refId": "REF-7A6C2A8E"
    }
  }
}