> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes. # create > Create a new caller ID entry and initiate verification. Create a new caller ID entry and initiate verification. SignalWire will place a phone call or send an SMS to verify ownership. ### Schema ```yaml openapi: 3.1.0 info: title: API version: 1.0.0 paths: /api/relay/rest/verified_caller_ids: post: operationId: subpackageVerifiedCallerId_create_verified_caller_id summary: Create verified caller ID description: >- Starts verification of an external phone number for use as an outbound caller ID and sends a verification code to that number. Use it when presenting a number the project does not own; use a purchased or imported project number directly instead. Complete the flow with [Validate verification code](/docs/apis/rest/verified-caller-id/validate-verification-code). #### Permissions The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Voice_. [Learn more about API scopes](/docs/platform/your-signalwire-api-space). tags: - subpackage_verifiedCallerId responses: '201': description: >- The request has succeeded and a new resource has been created as a result. content: application/json: schema: $ref: '#/components/schemas/VerifiedCallerIDResponse' '401': description: Access is unauthorized. content: application/json: schema: $ref: '#/components/schemas/Types.StatusCodes.StatusCode401' '422': description: The request failed validation. See errors for details. content: application/json: schema: $ref: '#/components/schemas/Types.StatusCodes.ValidationError' '500': description: An internal server error occurred. content: application/json: schema: $ref: '#/components/schemas/Types.StatusCodes.StatusCode500' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateVerifiedCallerIDRequest' tags: - name: subpackage_verifiedCallerId servers: - url: https://%7BYour_Space_Name%7D.signalwire.com description: SignalWire API components: schemas: CreateVerifiedCallerIDRequest: type: object properties: number: type: string description: >- String representing the phone number for the caller ID. This must be a valid, routeable phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164) that is able to receive a voice phone call for verification. name: type: string maxLength: 200 description: >- The name portion of the caller ID. If not provided, the default will be the formatted number. extension: type: string description: >- The extension of the phone number for the caller ID. This is only used when placing the verification call. required: - number description: Request body for creating a verified caller ID. title: CreateVerifiedCallerIDRequest uuid: type: string format: uuid description: Universal Unique Identifier. title: uuid VerifiedCallerIdResponseStatus: type: string enum: - Verified - Awaiting Verification description: The verification status for the caller ID. title: VerifiedCallerIdResponseStatus VerifiedCallerIDResponse: type: object properties: type: type: string description: The type of the returned object, this should be verified_caller_id. id: $ref: '#/components/schemas/uuid' description: The unique identifier of the Verified Caller ID on SignalWire. number: type: string description: >- String representing the phone number for the caller ID. This must be a valid, routeable phone number in E.164 format. name: type: string description: >- String representing the name portion of the caller ID. If not provided, the default will be the formatted number that has been provided. extension: type: string description: >- String representing the extension of the phone number for the caller ID. This is only used when placing the verification call. verified: type: boolean description: A boolean representing whether the number has been verified or not. verified_at: type: string format: date-time description: >- Nullable DateTime field representing the date and time that the number was verified. If the number has not been verified, it will be null. status: $ref: '#/components/schemas/VerifiedCallerIdResponseStatus' description: The verification status for the caller ID. required: - id - number - verified description: Response containing a single verified caller ID. title: VerifiedCallerIDResponse TypesStatusCodesStatusCode401Error: type: string enum: - Unauthorized title: TypesStatusCodesStatusCode401Error Types.StatusCodes.StatusCode401: type: object properties: error: $ref: '#/components/schemas/TypesStatusCodesStatusCode401Error' required: - error description: Access is unauthorized. title: Types.StatusCodes.StatusCode401 Types.StatusCodes.SpaceApiErrorItem: type: object properties: detail: type: string description: A description of what caused the error. status: type: string description: The HTTP status code. title: type: string description: A short summary of the error type. code: type: string description: The error code. required: - detail - status - title - code description: Details about a specific validation error. title: Types.StatusCodes.SpaceApiErrorItem Types.StatusCodes.ValidationError: type: object properties: errors: type: array items: $ref: '#/components/schemas/Types.StatusCodes.SpaceApiErrorItem' description: List of validation errors. required: - errors description: The request failed validation. See errors for details. title: Types.StatusCodes.ValidationError TypesStatusCodesStatusCode500Error: type: string enum: - Internal Server Error title: TypesStatusCodesStatusCode500Error Types.StatusCodes.StatusCode500: type: object properties: error: $ref: '#/components/schemas/TypesStatusCodesStatusCode500Error' required: - error description: An internal server error occurred. title: Types.StatusCodes.StatusCode500 ``` ## **Response Example** ### Response (201) ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "number": "+15551234567", "verified": false, "type": "verified_caller_id", "name": "C-3P0", "extension": "1234", "verified_at": "2024-01-15T09:30:00Z", "status": "Awaiting Verification" } ``` ## **Example** ```typescript {9} import { RestClient } from "@signalwire/sdk"; const client = new RestClient({ project: "your-project-id", token: "your-api-token", host: "your-space.signalwire.com" }); const caller = await client.verifiedCallers.create({ number: "+15551234567" }); console.log("Verification state:", caller.verificationState); ``` > Create a new caller ID entry and initiate verification.