> For the complete documentation index, see [llms.txt](https://apidocs.api19.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.api19.com/number-portability/update-port-out-pin.md).

# Update Port-Out PIN

Sets the port-out PIN on one or more DIDs on your account. Your current carrier asks for this PIN before it will release a number to another carrier.

Endpoint:

{% hint style="info" %}
POST <https://v1.api19.com/lnp/portability/update-pin>
{% endhint %}

Request parameters:&#x20;

<table><thead><tr><th>Parameter</th><th width="99.94921875">Type</th><th width="106.08984375">Required</th><th width="167.421875">Description</th><th>Rules</th></tr></thead><tbody><tr><td><code>key</code></td><td>string</td><td>Yes</td><td>Your API key.</td><td>Must be a valid, active API key.</td></tr><tr><td><code>pin</code></td><td>string</td><td>Yes</td><td>The new port-out PIN to set on every DID in the request.</td><td>Numbers only, 4–6 digits. Keep leading zeros (e.g. <code>0482</code>).</td></tr><tr><td><code>dids</code></td><td>string</td><td>Yes</td><td>The DIDs to update, as a comma-separated list of DID IDs.</td><td>Each value must be a numeric DID ID owned by your account or one of its sub-accounts. Duplicates and non-numeric values are ignored.</td></tr></tbody></table>

**Response fields :**&#x20;

<table><thead><tr><th width="197.53125">Field</th><th width="96.28515625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>status</code></td><td>string</td><td><code>ok</code> if the request was processed, <code>error</code> if it was rejected.</td></tr><tr><td><code>results</code></td><td>array</td><td>One entry per DID, returned when <code>status</code> is <code>ok</code>.</td></tr><tr><td><code>results[].did</code></td><td>string</td><td>The phone number, or the DID ID if the number wasn't found.</td></tr><tr><td><code>results[].status</code></td><td>string</td><td><code>ok</code> or <code>error</code> for this DID.</td></tr><tr><td><code>results[].message</code></td><td>string</td><td><code>PIN updated</code>, <code>DID not found</code>, <code>Not owned</code>, or <code>Failed to update</code>.</td></tr><tr><td><code>error</code></td><td>string</td><td>Why the request was rejected. Only present when <code>status</code> is <code>error</code>.</td></tr></tbody></table>

{% hint style="warning" %}
**Note:** a top-level `status` of `ok` means the request was accepted, not that every DID was updated. Check each entry in `results` to see which DIDs failed.
{% endhint %}

{% tabs %}
{% tab title="CURL post" %}

```php
curl -X POST https://v1.api19.com/lnp/portability/update-pin \
 -d "pin=1234" \
 -d "dids=1234,12314" \
 -d 'key=your-key'
```

{% endtab %}

{% tab title="Success Response" %}
Example response: all updated

{% code overflow="wrap" %}

```json
{  
    "status": "ok",  
    "results": [    
        {"did": "3055550101", "status": "ok", "message": "PIN updated" },    
        { "did": "3055550102", "status": "ok", "message": "PIN updated" },    
        { "did": "3055550147", "status": "ok", "message": "PIN updated" }  
    ]
}
```

{% endcode %}

Example response: partly updated

```json
{
  "status": "ok",
  "results": [
    { "did": "3055550101", "status": "ok", "message": "PIN updated" },
    { "did": "99999", "status": "error", "message": "DID not found" },
    { "did": "7865550188", "status": "error", "message": "Not owned" }
  ]
}
```

{% endtab %}

{% tab title="Errors" %}

```json
{
  "status": "error",
  "error": "PIN must be 4 to 6 digits",
  "verbose": "",
  "code": ""
}
```

{% endtab %}
{% endtabs %}

Error messages:&#x20;

| Error                       | Cause                                                  |
| --------------------------- | ------------------------------------------------------ |
| `pin and dids are required` | `pin` or `dids` is missing or empty.                   |
| `PIN must be 4 to 6 digits` | `pin` isn't 4–6 digits.                                |
| `Invalid dids`              | None of the values in `dids` is a valid numeric ID.    |
| `Missing PIN`               | The PIN was empty when it reached the routing service. |
| `No numbers selected`       | No DID IDs reached the routing service.                |
| `Unexpected error`          | The routing service didn't return a valid response.    |