---
title: "Create a new Virtual Reference Number"
method: POST
path: "/virtual_reference_numbers"
tags: ["Virtual Reference Numbers"]
---

# Create a new Virtual Reference Number

`POST /virtual_reference_numbers`

Creates a new Virtual Reference Number (VRN) for the specified Synthetic Account.

## Request body

- object
  - `external_uid` ExternalUid — unresolved $ref
  - `name` Name — unresolved $ref
  - `synthetic_account_uid` string, required — A unique id referring to the mapped, general Synthetic Account.
  - `routing_number` string, required — The ABA routing number associated with this VRN.

## Response `201`

A single registered Virtual Reference Number is returned

- object
  - `archived_at` string — The DateTime at which this VRN was archived. This value will be present if the status is archived. If in another state, the value will be null.
  - `created_at` string — The DateTime at which this VRN was created
  - `custodial_account_uid` string — A unique id referring to the mapped, Custodial Account.
  - `external_uid` ExternalUid — unresolved $ref
  - `instant_payment_rail_registration_status` Schema — unresolved $ref
  - `locked_at` string — The DateTime at which this VRN was locked. This value will be present if the status is locked. If in another state, the value will be null.
  - `lock_reason` 'admin' | 'customer_request' — Provided reason for locking the VRN.
  - `name` Name — unresolved $ref
  - `routing_number` string — The ABA routing number (if any) associated with this VRN.
  - `status` Schema — unresolved $ref
  - `synthetic_account_uid` Schema — unresolved $ref
  - `uid` string — Unique identifier for the VRN
  - `virtual_reference_number_last_four` string — Last 4 digits of the VRN
  - `virtual_reference_number` string — The VRN

## Other responses

- `422` — Creation Error

## Changes

- **2026-08-21** `54f4fe726d8f` — 3 breaking, 1 warning, 1 info
  - added `#/components/schemas/0` to the `external_uid` request property `allOf` list
  - the `name` request property type/format changed from ``/`` to `string`/``
  - the `allOf[subschema #1]/name` response's property type/format changed from ``/`` to `string`/`` for status `201`
  - the `name` request property's maxLength was set to `255`
  - …1 more

[Change history](https://skmtc.dev/newline53/apis/newline-platform-api/changes/virtual_reference_numbers/post.md)

---

[API](https://skmtc.dev/newline53/apis/newline-platform-api.md) · [All operations](https://skmtc.dev/newline53/apis/newline-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/newline53/newline-platform-api/revisions/54f4fe726d8f/schema)