> For the complete documentation index, see [llms.txt](https://docs.360dialog.com/partner/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.360dialog.com/partner/partner-api/api-reference/preverified-numbers-management.md).

# Preverified Numbers Management

## List the partner's pre-verified phone numbers

> Returns the phone numbers in the partner's pre-verified pool. Optional query params\
> filter by verification status and exact phone number; country\_code does not filter\
> but orders matching numbers first.

```json
{"openapi":"3.1.0","info":{"title":"Partners V2 API","version":"2.0.0"},"tags":[{"name":"Preverified Numbers Management"}],"servers":[{"description":"Production Server","url":"https://hub.360dialog.io"}],"security":[{"PartnerApiKeyV2":[]},{"Bearer":[]}],"components":{"securitySchemes":{"PartnerApiKeyV2":{"type":"apiKey","name":"X-API-Key","in":"header","description":"API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method."},"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication. Token obtained via /api/v2/token endpoint."}},"schemas":{"PreverifiedNumberOut":{"type":"object","properties":{"preverified_phone_number_id":{"type":"string","description":"Meta's pre-verified phone number ID."},"phone_number":{"type":"string","description":"The registered phone number, digits only."},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code (lowercase), derived from the phone number.","nullable":true},"partner_id":{"type":"string","description":"Partner ID the number belongs to.","nullable":true},"code_verification_status":{"type":"string","description":"Verification status of the number."},"created_at":{"type":"string","description":"ISO 8601 creation timestamp."}},"required":["code_verification_status","country_code","created_at","partner_id","phone_number","preverified_phone_number_id"],"additionalProperties":false},"DefaultValidationError":{"type":"object","properties":{"meta":{"allOf":[{"$ref":"#/components/schemas/MetaSchemaErrorWithDetails"}]}},"required":["meta"],"additionalProperties":false},"MetaSchemaErrorWithDetails":{"type":"object","properties":{"developer_message":{"type":"string"},"http_code":{"type":"integer"},"success":{"type":"boolean"},"360dialog_trace_id":{"type":"string","description":"Trace ID for debugging purposes"},"details":{"type":"object","description":"Additional error data","additionalProperties":{}}},"required":["developer_message","http_code","success"],"additionalProperties":false},"DefaultHttpError":{"type":"object","properties":{"meta":{"allOf":[{"$ref":"#/components/schemas/_MetaSchemaError"}]}},"required":["meta"],"additionalProperties":false},"_MetaSchemaError":{"type":"object","properties":{"developer_message":{"type":"string"},"http_code":{"type":"integer"},"success":{"type":"boolean"},"360dialog_trace_id":{"type":"string","description":"Trace ID for debugging purposes"}},"required":["developer_message","http_code","success"],"additionalProperties":false}}},"paths":{"/api/v2/partners/{partner_id}/preverified-numbers":{"get":{"parameters":[{"in":"query","name":"code_verification_status","description":"Filter by verification status. When 'VERIFIED', numbers whose verification has expired on Meta's side are additionally excluded.","schema":{"type":"string","enum":["NOT_VERIFIED","VERIFIED","EXPIRED"]},"required":false},{"in":"query","name":"phone_number","description":"Filter by exact phone number. Digits only, no leading '+'.","schema":{"type":"string","minLength":6,"maxLength":20,"pattern":"^\\d+$"},"required":false},{"in":"query","name":"country_code","description":"Preferred ISO 3166-1 alpha-2 country code (lowercase). Does not filter - numbers with this country code are returned first.","schema":{"type":"string"},"required":false},{"in":"path","name":"partner_id","description":"The ID of the partner.","schema":{"type":"string"},"required":true}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PreverifiedNumberOut"}}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultValidationError"}}},"description":"Wrong payload"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultHttpError"}}},"description":"Not found"}},"tags":["Preverified Numbers Management"],"summary":"List the partner's pre-verified phone numbers","description":"Returns the phone numbers in the partner's pre-verified pool. Optional query params\nfilter by verification status and exact phone number; country_code does not filter\nbut orders matching numbers first.","operationId":"get_preverified_numbers_endpoints_list_preverified_numbers"}}}}
```

## Add a pre-verified phone number to the partner's pool

> Registers a phone number with Meta's Graph API and shares it with the partner's business.

```json
{"openapi":"3.1.0","info":{"title":"Partners V2 API","version":"2.0.0"},"tags":[{"name":"Preverified Numbers Management"}],"servers":[{"description":"Production Server","url":"https://hub.360dialog.io"}],"security":[{"PartnerApiKeyV2":[]},{"Bearer":[]}],"components":{"securitySchemes":{"PartnerApiKeyV2":{"type":"apiKey","name":"X-API-Key","in":"header","description":"API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method."},"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication. Token obtained via /api/v2/token endpoint."}},"schemas":{"PreverifiedNumberOut":{"type":"object","properties":{"preverified_phone_number_id":{"type":"string","description":"Meta's pre-verified phone number ID."},"phone_number":{"type":"string","description":"The registered phone number, digits only."},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code (lowercase), derived from the phone number.","nullable":true},"partner_id":{"type":"string","description":"Partner ID the number belongs to.","nullable":true},"code_verification_status":{"type":"string","description":"Verification status of the number."},"created_at":{"type":"string","description":"ISO 8601 creation timestamp."}},"required":["code_verification_status","country_code","created_at","partner_id","phone_number","preverified_phone_number_id"],"additionalProperties":false},"DefaultValidationError":{"type":"object","properties":{"meta":{"allOf":[{"$ref":"#/components/schemas/MetaSchemaErrorWithDetails"}]}},"required":["meta"],"additionalProperties":false},"MetaSchemaErrorWithDetails":{"type":"object","properties":{"developer_message":{"type":"string"},"http_code":{"type":"integer"},"success":{"type":"boolean"},"360dialog_trace_id":{"type":"string","description":"Trace ID for debugging purposes"},"details":{"type":"object","description":"Additional error data","additionalProperties":{}}},"required":["developer_message","http_code","success"],"additionalProperties":false},"AddPreverifiedNumberIn":{"type":"object","properties":{"phone_number":{"type":"string","minLength":6,"maxLength":20,"pattern":"^\\d+$","description":"Phone number to register as pre-verified. Digits only, no leading '+'."}},"required":["phone_number"],"additionalProperties":false}}},"paths":{"/api/v2/partners/{partner_id}/preverified-numbers":{"post":{"parameters":[{"in":"path","name":"partner_id","description":"The ID of the partner.","schema":{"type":"string"},"required":true}],"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreverifiedNumberOut"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultValidationError"}}},"description":"Wrong payload"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultValidationError"}}},"description":"Not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultValidationError"}}},"description":"Conflict"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultValidationError"}}},"description":"Server error"}},"tags":["Preverified Numbers Management"],"summary":"Add a pre-verified phone number to the partner's pool","description":"Registers a phone number with Meta's Graph API and shares it with the partner's business.","operationId":"post_preverified_numbers_endpoints_add_preverified_number","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddPreverifiedNumberIn"}}}}}}}}
```

## Delete a preverified phone number

> Deletes the number from Meta's Graph API and soft-deletes it from the\
> partner's pre-verified pool. Returns 404 when the number is not in the pool.

```json
{"openapi":"3.1.0","info":{"title":"Partners V2 API","version":"2.0.0"},"tags":[{"name":"Preverified Numbers Management"}],"servers":[{"description":"Production Server","url":"https://hub.360dialog.io"}],"security":[{"PartnerApiKeyV2":[]},{"Bearer":[]}],"components":{"securitySchemes":{"PartnerApiKeyV2":{"type":"apiKey","name":"X-API-Key","in":"header","description":"API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method."},"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication. Token obtained via /api/v2/token endpoint."}},"schemas":{"PreverifiedNumberServiceResponse":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"data":{"nullable":true}},"required":["message","status"],"additionalProperties":false},"DefaultValidationError":{"type":"object","properties":{"meta":{"allOf":[{"$ref":"#/components/schemas/MetaSchemaErrorWithDetails"}]}},"required":["meta"],"additionalProperties":false},"MetaSchemaErrorWithDetails":{"type":"object","properties":{"developer_message":{"type":"string"},"http_code":{"type":"integer"},"success":{"type":"boolean"},"360dialog_trace_id":{"type":"string","description":"Trace ID for debugging purposes"},"details":{"type":"object","description":"Additional error data","additionalProperties":{}}},"required":["developer_message","http_code","success"],"additionalProperties":false}}},"paths":{"/api/v2/partners/{partner_id}/preverified-numbers/{preverified_phone_number_id}":{"delete":{"parameters":[{"in":"path","name":"preverified_phone_number_id","description":"Meta's phone number id","schema":{"type":"string"},"required":true},{"in":"path","name":"partner_id","description":"The ID of the partner.","schema":{"type":"string"},"required":true}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreverifiedNumberServiceResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultValidationError"}}},"description":"Wrong payload"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultValidationError"}}},"description":"Not found"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultValidationError"}}},"description":"Server error"}},"tags":["Preverified Numbers Management"],"summary":"Delete a preverified phone number","description":"Deletes the number from Meta's Graph API and soft-deletes it from the\npartner's pre-verified pool. Returns 404 when the number is not in the pool.","operationId":"delete_preverified_numbers_endpoints_delete_preverified_number"}}}}
```

## Verify OTP for a preverified phone number

> This endpoint is used to verify the OTP that was received for a preverified number from Meta API.

```json
{"openapi":"3.1.0","info":{"title":"Partners V2 API","version":"2.0.0"},"tags":[{"name":"Preverified Numbers Management"}],"servers":[{"description":"Production Server","url":"https://hub.360dialog.io"}],"security":[{"PartnerApiKeyV2":[]},{"Bearer":[]}],"components":{"securitySchemes":{"PartnerApiKeyV2":{"type":"apiKey","name":"X-API-Key","in":"header","description":"API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method."},"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication. Token obtained via /api/v2/token endpoint."}},"schemas":{"PreverifiedNumberOut":{"type":"object","properties":{"preverified_phone_number_id":{"type":"string","description":"Meta's pre-verified phone number ID."},"phone_number":{"type":"string","description":"The registered phone number, digits only."},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code (lowercase), derived from the phone number.","nullable":true},"partner_id":{"type":"string","description":"Partner ID the number belongs to.","nullable":true},"code_verification_status":{"type":"string","description":"Verification status of the number."},"created_at":{"type":"string","description":"ISO 8601 creation timestamp."}},"required":["code_verification_status","country_code","created_at","partner_id","phone_number","preverified_phone_number_id"],"additionalProperties":false},"DefaultValidationError":{"type":"object","properties":{"meta":{"allOf":[{"$ref":"#/components/schemas/MetaSchemaErrorWithDetails"}]}},"required":["meta"],"additionalProperties":false},"MetaSchemaErrorWithDetails":{"type":"object","properties":{"developer_message":{"type":"string"},"http_code":{"type":"integer"},"success":{"type":"boolean"},"360dialog_trace_id":{"type":"string","description":"Trace ID for debugging purposes"},"details":{"type":"object","description":"Additional error data","additionalProperties":{}}},"required":["developer_message","http_code","success"],"additionalProperties":false},"PreverifiedPhoneNumberVerifyOTPIn":{"type":"object","properties":{"code":{"type":"string","description":"OTP code to verify"}},"required":["code"],"additionalProperties":false}}},"paths":{"/api/v2/partners/{partner_id}/preverified-numbers/{preverified_phone_number_id}/verify-otp":{"post":{"parameters":[{"in":"path","name":"preverified_phone_number_id","description":"Meta's phone number id","schema":{"type":"string"},"required":true},{"in":"path","name":"partner_id","description":"The ID of the partner.","schema":{"type":"string"},"required":true}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreverifiedNumberOut"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultValidationError"}}},"description":"Wrong payload"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultValidationError"}}},"description":"Not found"}},"tags":["Preverified Numbers Management"],"summary":"Verify OTP for a preverified phone number","description":"This endpoint is used to verify the OTP that was received for a preverified number from Meta API.","operationId":"post_preverified_numbers_endpoints_verify_otp","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreverifiedPhoneNumberVerifyOTPIn"}}}}}}}}
```

## Request OTP for a preverified phone number

> This endpoint is used to request an OTP for a preverified number from Meta API.

```json
{"openapi":"3.1.0","info":{"title":"Partners V2 API","version":"2.0.0"},"tags":[{"name":"Preverified Numbers Management"}],"servers":[{"description":"Production Server","url":"https://hub.360dialog.io"}],"security":[{"PartnerApiKeyV2":[]},{"Bearer":[]}],"components":{"securitySchemes":{"PartnerApiKeyV2":{"type":"apiKey","name":"X-API-Key","in":"header","description":"API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method."},"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication. Token obtained via /api/v2/token endpoint."}},"schemas":{"PreverifiedNumberServiceResponse":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"data":{"nullable":true}},"required":["message","status"],"additionalProperties":false},"DefaultValidationError":{"type":"object","properties":{"meta":{"allOf":[{"$ref":"#/components/schemas/MetaSchemaErrorWithDetails"}]}},"required":["meta"],"additionalProperties":false},"MetaSchemaErrorWithDetails":{"type":"object","properties":{"developer_message":{"type":"string"},"http_code":{"type":"integer"},"success":{"type":"boolean"},"360dialog_trace_id":{"type":"string","description":"Trace ID for debugging purposes"},"details":{"type":"object","description":"Additional error data","additionalProperties":{}}},"required":["developer_message","http_code","success"],"additionalProperties":false},"PreverifiedPhoneNumberRequestOTPIn":{"type":"object","properties":{"code_method":{"description":"OTP delivery method","enum":["sms","voice"]},"language":{"type":"string","minLength":1,"description":"Language/locale for the OTP message"}},"required":["code_method","language"],"additionalProperties":false}}},"paths":{"/api/v2/partners/{partner_id}/preverified-numbers/{preverified_phone_number_id}/request-otp":{"post":{"parameters":[{"in":"path","name":"preverified_phone_number_id","description":"Meta's phone number id","schema":{"type":"string"},"required":true},{"in":"path","name":"partner_id","description":"The ID of the partner.","schema":{"type":"string"},"required":true}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreverifiedNumberServiceResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultValidationError"}}},"description":"Wrong payload"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultValidationError"}}},"description":"Not found"}},"tags":["Preverified Numbers Management"],"summary":"Request OTP for a preverified phone number","description":"This endpoint is used to request an OTP for a preverified number from Meta API.","operationId":"post_preverified_numbers_endpoints_request_otp","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreverifiedPhoneNumberRequestOTPIn"}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.360dialog.com/partner/partner-api/api-reference/preverified-numbers-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.