# Add an allow or block list entry (/docs/api-reference/risk/create-risk-list-entry)

Adds an email address (matched by mailbox), domain (with its subdomains), IP address or CIDR range, AS number, country or user id to the environment's allow or block list. An allow-list match makes the decision `allow` whatever else fired; a block-list match makes it `block`. Adding an entry that already exists returns it with status 200.

`POST https://api.coss.com/v1/risk/list_entries`

Authenticate with your API key as a bearer token (`Authorization: Bearer coss_test_…`). Responses are JSON with snake_case fields; errors are `{ error: { type, code, message, param?, issues?, request_id } }` (https://coss.com/docs/api-reference/errors.md).

## Request body

- `list` ("allow" | "block", required): Which list: `allow` or `block`.
- `type` ("email" | "domain" | "ip" | "asn" | "country" | "user", required): `email` (matched by mailbox, dots and `+tags` folded), `domain` (subdomains included), `ip` (an address or CIDR range), `asn`, `country` (ISO 3166-1 alpha-2), `user` (your user id).
- `value` (string, required, 1-320 characters): What to match: the address, domain, IP, CIDR range, ASN or other value of its `type`.
- `note` (string, at most 500 characters): Your note about it.
- `expires_at` (string, date-time): The entry stops matching at this time (it is kept until deleted).

## Example request

TypeScript (the `coss` package):

```ts
import { Coss } from "coss";

const coss = new Coss({
  apiKey: process.env.COSS_API_KEY,
  baseUrl: "https://api.coss.com",
});

const { data, error } = await coss.risk.lists.add("block", {
  domain: "evil.example",
  note: "Card testing",
});
```

HTTP:

```sh
curl -X POST "https://api.coss.com/v1/risk/list_entries" \
  -H "Authorization: Bearer $COSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "list": "block",
  "type": "domain",
  "value": "evil.example",
  "note": "Card testing"
}'
```

Python:

```python
from coss import Coss

client = Coss()  # api_key= or COSS_API_KEY

client.risk.lists.add(
    list_="block",
    type="domain",
    value="evil.example",
    note="Card testing",
)
```

Go:

```go
import (
	"context"

	coss "github.com/cosscom/coss-go"
	cossclient "github.com/cosscom/coss-go/client"
	risk "github.com/cosscom/coss-go/risk"
)

client := cossclient.NewClient() // option.WithAPIKey(…) or COSS_API_KEY

request := &risk.CreateRiskListEntryRequest{
    List: coss.RiskListBlock,
    Type: coss.RiskListEntryTypeDomain,
    Value: "evil.example",
    Note: coss.String(
        "Card testing",
    ),
}
client.Risk.Lists.Add(
    context.TODO(),
    request,
)
```

Ruby:

```ruby
require "coss"

client = Coss::Client.new # api_key: or COSS_API_KEY

client.risk.lists.add(
  list: "block",
  type: "domain",
  value: "evil.example",
  note: "Card testing"
)
```

PHP:

```php
<?php

use Coss\Coss;
use Coss\Risk\Lists\Requests\CreateRiskListEntryRequest;
use Coss\Types\RiskList;
use Coss\Types\RiskListEntryType;

$client = new Coss(); // apiKey: or COSS_API_KEY

$client->risk->lists->add(
    new CreateRiskListEntryRequest([
        'list' => RiskList::Block->value,
        'type' => RiskListEntryType::Domain->value,
        'value' => 'evil.example',
        'note' => 'Card testing',
    ]),
);
```

Java:

```java
import com.coss.Coss;
import com.coss.resources.risk.lists.requests.CreateRiskListEntryRequest;
import com.coss.types.RiskList;
import com.coss.types.RiskListEntryType;

Coss client = Coss.builder().build(); // .apiKey(…) or COSS_API_KEY

client.risk().lists().add(
    CreateRiskListEntryRequest
        .builder()
        .list(RiskList.BLOCK)
        .type(RiskListEntryType.DOMAIN)
        .value("evil.example")
        .note("Card testing")
        .build()
);
```

.NET:

```csharp
using Coss;
using Coss.Risk;

var client = new CossClient(); // apiKey: or COSS_API_KEY

await client.Risk.Lists.AddAsync(
    new CreateRiskListEntryRequest
    {
        List = RiskList.Block,
        Type = RiskListEntryType.Domain,
        Value = "evil.example",
        Note = "Card testing",
    }
);
```

## Response 200

The entry already existed.

- `object` ("risk_list_entry", required)
- `id` (string, required)
- `list` ("allow" | "block", required): Which list: `allow` or `block`.
- `type` ("email" | "domain" | "ip" | "asn" | "country" | "user", required): `email` (matched by mailbox, dots and `+tags` folded), `domain` (subdomains included), `ip` (an address or CIDR range), `asn`, `country` (ISO 3166-1 alpha-2), `user` (your user id).
- `value` (string, required): Normalized: emails as their mailbox, CIDR ranges canonical, ASNs as numbers.
- `note` (string | null, required): Your note about it. `null`: none.
- `expires_at` (string | null, required, date-time): When it stops matching. `null`: never.
- `created_at` (string, required, date-time)

Example:

```json
{
  "object": "risk_list_entry",
  "id": "rskle_01k7c8m4q2f3e9v6t5r1n0p8yz",
  "list": "block",
  "type": "domain",
  "value": "evil.example",
  "note": "Card testing",
  "expires_at": null,
  "created_at": "2026-01-15T09:30:00.000Z"
}
```

## Response 201

The new entry.

- `object` ("risk_list_entry", required)
- `id` (string, required)
- `list` ("allow" | "block", required): Which list: `allow` or `block`.
- `type` ("email" | "domain" | "ip" | "asn" | "country" | "user", required): `email` (matched by mailbox, dots and `+tags` folded), `domain` (subdomains included), `ip` (an address or CIDR range), `asn`, `country` (ISO 3166-1 alpha-2), `user` (your user id).
- `value` (string, required): Normalized: emails as their mailbox, CIDR ranges canonical, ASNs as numbers.
- `note` (string | null, required): Your note about it. `null`: none.
- `expires_at` (string | null, required, date-time): When it stops matching. `null`: never.
- `created_at` (string, required, date-time)

Example:

```json
{
  "object": "risk_list_entry",
  "id": "rskle_01k7c8m4q2f3e9v6t5r1n0p8yz",
  "list": "block",
  "type": "domain",
  "value": "evil.example",
  "note": "Card testing",
  "expires_at": null,
  "created_at": "2026-01-15T09:30:00.000Z"
}
```

## Errors

- `400`: The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).
- `401`: The API key is missing, invalid, revoked or expired (`authentication_error`).
- `403`: The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).
- `413`: The request body is larger than 5 MB (`payload_too_large`).
- `415`: The body is not sent as `application/json` (`unsupported_media_type`).
- `422`: The body failed validation (`validation_error`, see `issues`) or `value` is not a valid value of its `type` (`invalid_list_value`).
- `429`: Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).
- `500`: Unexpected server error (`api_error` / `internal_error`).
- `503`: The API key could not be verified right now; retry (`service_unavailable`).