Remove addresses from the address suppression list

DELETE/api/v1/address/suppressions

authentication: Secret API key as a bearer token
billing: Free.

Removes up to 1,000 addresses per request by the address itself, for a caller that knows the address but not the id it was filed under. Each value is a written address or an object of the same fields the import takes, and is folded against country the way the list stores it — so 10 downing st, london sw1a2aa removes the entry filed as 10 Downing Street, London, SW1A 2AA. country is required: an address folds to a building against one country's format, and a value that folds to nothing would be reported as not on a list it is on. An item may still name its own country.

The answer names every address it was given, written the way the list labels it: removed are the ones that were on the list and no longer are, not_found the ones that were not on it — including an address that names no building, and one that is on another account's list. Two spellings of one building both count as removed.

The cap is 1,000 rather than the import's 10,000 because the answer names every value back: a request over the cap is a 422 and removes nothing. Removing an entry means the address is looked up fresh the next time a batch, bulk or monitor run meets it.

Request body

field	type	description
valuesrequired	string[]	1 to 1,000 addresses, each a written line or an object of the separated fields.
values[].address	string	At most 500 characters.
values[].address_line1	string	At most 255 characters.
values[].address_line2	string	At most 255 characters.
values[].organization	string	At most 200 characters.
values[].dependent_locality	string	At most 100 characters.
values[].locality	string	At most 100 characters.
values[].administrative_area	string	At most 100 characters.
values[].postal_code	string	At most 32 characters.
values[].po_box	string	At most 64 characters.
values[].country	string \| null	An ISO 3166-1 alpha-2 code for this address.
countryrequired	string	The ISO 3166-1 alpha-2 country every value is read against.

Example request

curl -X DELETE https://spaw.co/api/v1/address/suppressions \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "values": [
    "10 downing st, london sw1a2aa",
    {
      "address_line1": "221B Baker Street",
      "postal_code": "NW1 6XE"
    }
  ],
  "country": "GB"
}'

const response = await fetch('https://spaw.co/api/v1/address/suppressions', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer sk_live_…',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "values": [
      "10 downing st, london sw1a2aa",
      {
        "address_line1": "221B Baker Street",
        "postal_code": "NW1 6XE"
      }
    ],
    "country": "GB"
  }),
});
const result = await response.json();

import requests

response = requests.delete(
    'https://spaw.co/api/v1/address/suppressions',
    headers={'Authorization': 'Bearer sk_live_…'},
    json={
        'values': [
            '10 downing st, london sw1a2aa',
            {
                'address_line1': '221B Baker Street',
                'postal_code': 'NW1 6XE'
            }
        ],
        'country': 'GB'
    },
)
result = response.json()

$ch = curl_init('https://spaw.co/api/v1/address/suppressions');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_live_…', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'values' => [
            '10 downing st, london sw1a2aa',
            [
                'address_line1' => '221B Baker Street',
                'postal_code' => 'NW1 6XE'
            ]
        ],
        'country' => 'GB'
    ]),
]);
$result = json_decode(curl_exec($ch), true);

from spaw import Client

client = Client('sk_live_…')
result = client.remove_address_suppressions([
    '10 downing st, london sw1a2aa',
    {
        'address_line1': '221B Baker Street',
        'postal_code': 'NW1 6XE'
    }
], country='GB')

import Spaw from 'spaw';

const spaw = new Spaw({ apiKey: 'sk_live_…' });
const result = await spaw.removeAddressSuppressions([
    '10 downing st, london sw1a2aa',
    {
        address_line1: '221B Baker Street',
        postal_code: 'NW1 6XE'
    }
], {
    country: 'GB'
});

use Spaw\Client;

$spaw = new Client('sk_live_…');
$result = $spaw->removeAddressSuppressions([
    '10 downing st, london sw1a2aa',
    [
        'address_line1' => '221B Baker Street',
        'postal_code' => 'NW1 6XE'
    ]
], country: 'GB');

This endpoint has no console on its page. It writes to your account. A documentation page can show you the request; making the change is for the dashboard or for a call you make yourself.

Responses

200Which of the addresses were on the list and which were not.

{
    "success": true,
    "data": {
        "removed": [
            "10 downing st, london sw1a2aa"
        ],
        "not_found": [
            "221B Baker Street, NW1 6XE"
        ]
    }
}

401The key is missing, malformed, or revoked.

{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Provide a valid API key as a bearer token.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

422The request body could not be validated; `error.errors` lists the fields.

{
    "success": false,
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "The email field is required.",
        "errors": {
            "email": [
                "The email field is required."
            ]
        },
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

429Over 5 requests per second for the key. Retry after the limit resets.

{
    "success": false,
    "error": {
        "code": "RATE_LIMITED",
        "message": "Too many requests. Retry after the limit resets.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

Error codes

Failures answer { success: false, error: { code, message, request_id } }. Each code has its own page.

markdown version·openapi.json