> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear llista blanca: API de llistes personalitzades

> Didit: POST /v3/lists/ crea una llista blanca o personalitzada. Les llistes de bloqueig del sistema es creen automàticament. Pagament per crida.



Prompt de l'API per crear una llista
        Copia el prompt al porta-retalls



      
      

\<pre>

\`Create a new allowlist or custom list in my Didit application through the Management API.

Endpoint:
POST https://verification.didit.me/v3/lists/

Authentication:
Use the x-api-key header with my Didit API key. A scoped API key needs workflows: write.

Goal:
\- Create an allowlist (matching items are treated as trusted, for example to skip a duplicated-face or duplicated-IP action; it never overrides a blocklist match) or a custom list (for workflow conditions, transaction rules, or manual review).
\- System blocklists are provisioned by Didit, one per entry type. You cannot create a blocklist.

Request body (application/json):
\{
"name": "Trusted office IPs",          // required, at most 255 characters, unique among the application's lists
"description": "Office egress ranges", // optional
"list_type": "allowlist",              // required: "allowlist" or "custom"
"entry_type": "ip_address"             // required: face | document | phone | email | ip_address | device_fingerprint | wallet_address | bank_account | country | user | business | key
}

entry_type is fixed once the list exists: it decides how entry values are validated and matched.

Example call:
curl -X POST "https://verification.didit.me/v3/lists/" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Trusted office IPs", "list_type": "allowlist", "entry_type": "ip_address"}'

Example response (201):
\{
"uuid": "66666666-7777-8888-9999-000000000000",
"name": "Trusted office IPs",
"description": "",
"list_type": "allowlist",
"entry_type": "ip_address",
"is_system": false,
"entry_count": 0,
"last_entry_added_at": null,
"created_at": "2026-10-12T09:15:44.031876Z",
"updated_at": "2026-10-12T09:15:44.031876Z"
}

Persist the returned uuid: use it as list_uuid in the entry calls, and as the value of a workflow or transaction rule condition with value_type "list".

Failure modes:
\- 400: list_type is "blocklist", a required field is missing, name is longer than 255 characters, entry_type is unknown, or another list of the application already has this name ({ "name": ["A list with this name already exists for this application."] }).
\- 401: the API key has expired.
\- 403: missing x-api-key (a wrong, revoked or expired key gets 401) ({ "detail": "You do not have permission to perform this action." }), or a scoped key without workflows: write.
\- 429: rate limited (see /integration/rate-limiting); back off and retry.

Side effects:
\- Creates a new list in the application the API key belongs to.

For the full integration shape, see /integration/integration-prompt.`

\</pre>



      
      

Enganxa a

Crea una llista per a la teva aplicació. Només es poden crear llistes `allowlist` i `custom`: Didit crea una llista de bloqueig del sistema per cada tipus d'entrada, i hi afegeixes elements amb [Crea una entrada](https://docs.didit.me/ca/management-api/lists/create-entry.md).Tria `entry_type` amb cura: no es pot canviar més tard i determina com es valida cada valor quan l'afegeixes. Consulta [Llistes](https://docs.didit.me/ca/management-api/lists/overview.md) per saber què fa cada tipus de llista.


## OpenAPI

````yaml ca/openapi-25.json POST /v3/lists/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API de verificació d'identitat. Autentica't amb la capçalera x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/lists/:
    post:
      tags:
        - Lists
      summary: Crea una llista
      description: >-
        Crea una llista d'admesos o una llista personalitzada a l'aplicació a la
        qual pertany la clau d'API. Les llistes de bloqueig no es poden crear:
        Didit proveeix una llista de bloqueig del sistema per tipus d'entrada, i
        s'hi afegeixen elements amb [Crea una entrada de
        llista](https://docs.didit.me/ca/management-api/lists/create-entry).
        `entry_type` no pot canviar després de la creació i determina com es
        validen i coincideixen els valors de les entrades. Les entrades de la
        llista d'admesos marquen els elements coincidents com de confiança (per
        exemple, una llista d'admesos de cares omet l'acció de duplicació
        facial) i mai no anul·len una coincidència amb la llista de bloqueig;
        fes referència a qualsevol llista des d'una condició de regla de flux de
        treball o de transacció amb `value_type: "list"`. Una clau d'API amb
        àmbit necessita `workflows: write`.
      operationId: create_list
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - list_type
                - entry_type
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: >-
                    Nom de la llista. Ha de ser diferent del nom de qualsevol
                    altra llista de l'aplicació, incloses les llistes del
                    sistema.
                description:
                  type: string
                  default: ''
                  description: Descripció opcional en text lliure.
                list_type:
                  type: string
                  enum:
                    - allowlist
                    - custom
                  description: '`allowlist` o `custom`. `blocklist` es rebutja amb `400`.'
                entry_type:
                  type: string
                  enum:
                    - face
                    - document
                    - phone
                    - email
                    - ip_address
                    - device_fingerprint
                    - wallet_address
                    - bank_account
                    - country
                    - user
                    - business
                    - key
                  description: >-
                    Què conté la llista: `face`, `document` (número de
                    document), `phone`, `email`, `ip_address` (adreça o rang
                    CIDR), `device_fingerprint`, `wallet_address`,
                    `bank_account`, `country` (ISO 3166-1 alpha-3), `user` o
                    `business` (el teu `vendor_data`), o `key` (qualsevol
                    cadena). Decideix com es validen i es comparen els valors de
                    les entrades. No es pot modificar posteriorment.
            examples:
              IP allowlist:
                value:
                  name: Trusted office IPs
                  description: Office egress ranges
                  list_type: allowlist
                  entry_type: ip_address
              Custom country list:
                value:
                  name: Enhanced due diligence countries
                  list_type: custom
                  entry_type: country
      responses:
        '201':
          description: S'ha creat la llista.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplianceList'
              examples:
                New allowlist:
                  value:
                    uuid: 22222222-3333-4444-5555-666666666666
                    name: Trusted office IPs
                    description: Office egress ranges
                    list_type: allowlist
                    entry_type: ip_address
                    is_system: false
                    entry_count: 0
                    last_entry_added_at: null
                    created_at: '2026-10-12T09:15:44.031876Z'
                    updated_at: '2026-10-12T09:15:44.031876Z'
        '400':
          description: El cos no és vàlid.
          content:
            application/json:
              examples:
                Blocklist refused:
                  value:
                    list_type:
                      - >-
                        Cannot create additional blocklist lists. System
                        blocklists are auto-created for each application.
                Duplicate name:
                  value:
                    name:
                      - >-
                        A list with this name already exists for this
                        application.
                Missing fields:
                  value:
                    name:
                      - This field is required.
                    list_type:
                      - This field is required.
                    entry_type:
                      - This field is required.
                Unknown entry type:
                  value:
                    entry_type:
                      - '"iban" is not a valid choice.'
                Name too long:
                  value:
                    name:
                      - Ensure this field has no more than 255 characters.
        '401':
          description: >-
            La clau d'API amb abast ha caducat. Altres fallades d'autenticació
            retornen `403`.
          content:
            application/json:
              examples:
                Expired API key:
                  value:
                    detail: This API key has expired.
        '403':
          description: >-
            Falta la capçalera `x-api-key` (una clau incorrecta, revocada o
            caducada rep un `401`), o una clau d'API amb àmbit no té `workflows:
            write` o s'utilitza des d'una adreça IP fora de la seva llista
            d'admesos.
          content:
            application/json:
              examples:
                Missing or invalid API key:
                  value:
                    detail: You do not have permission to perform this action.
                Scoped key without workflows access:
                  value:
                    detail: This API key has no write access to workflows.
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST 'https://verification.didit.me/v3/lists/' \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "name": "Trusted office IPs",
                "description": "Office egress ranges",
                "list_type": "allowlist",
                "entry_type": "ip_address"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.lists.create(
                name="Trusted office IPs",
                description="Office egress ranges",
                list_type="allowlist",
                entry_type="ip_address",
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

            // Reads DIDIT_API_KEY.
            const didit = new Didit();

            const result = await didit.lists.create({
              name: "Trusted office IPs",
              description: "Office egress ranges",
              list_type: "allowlist",
              entry_type: "ip_address",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Create(ctx, didit.ListsCreateParams{\n\tName:        \"Trusted office IPs\",\n\tDescription: didit.String(\"Office egress ranges\"),\n\tListType:    \"allowlist\",\n\tEntryType:   \"ip_address\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: |-
            import me.didit.Didit;
            import me.didit.types.ListsCreateParams;

            // Reads DIDIT_API_KEY.
            Didit client = new Didit();

            var result = client.lists().create(ListsCreateParams.builder()
                    .name("Trusted office IPs")
                    .description("Office egress ranges")
                    .listType(ListsCreateParams.ListType.of("allowlist"))
                    .entryType(ListsCreateParams.EntryType.of("ip_address"))
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->lists->create([
                'name' => 'Trusted office IPs',
                'description' => 'Office egress ranges',
                'list_type' => 'allowlist',
                'entry_type' => 'ip_address',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.lists.create(
              name: "Trusted office IPs",
              description: "Office egress ranges",
              list_type: "allowlist",
              entry_type: "ip_address"
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: |-
            using System;
            using System.Text.Json;
            using Didit;

            // Reads DIDIT_API_KEY.
            using var client = new DiditClient();

            var result = await client.Lists.CreateAsync(new ListsCreateParams
            {
                Name = "Trusted office IPs",
                Description = "Office egress ranges",
                ListType = "allowlist",
                EntryType = "ip_address",
            });
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    ComplianceList:
      type: object
      description: >-
        Una llista de bloqueig, llista de permesos o llista personalitzada d'una
        aplicació.
      required:
        - uuid
        - name
        - description
        - list_type
        - entry_type
        - is_system
        - entry_count
        - last_entry_added_at
        - created_at
        - updated_at
      properties:
        uuid:
          type: string
          format: uuid
          description: >-
            Identificador de la llista. Utilitza'l com a `list_uuid` als
            endpoints de llistes i entrades, i com a valor d'una condició de
            regla de flux de treball o de transacció amb `value_type: "list"`.
        name:
          type: string
          maxLength: 255
          description: Nom de la llista, únic entre les llistes de l'aplicació.
        description:
          type: string
          description: Descripció de text lliure. Cadena buida si no s'ha definit.
        list_type:
          type: string
          enum:
            - blocklist
            - allowlist
            - custom
          description: >-
            `blocklist`: una coincidència rebutja la sessió o la transacció
            (només llistes del sistema, una per tipus d'entrada). `allowlist`:
            els elements coincidents són de confiança; per exemple, una llista
            d'autorització facial omet l'acció de detecció de cares duplicades;
            mai no anul·la una coincidència amb una llista de bloqueig.
            `custom`: s'utilitza en condicions de regles de fluxos de treball i
            transaccions (`value_type: "list"`).
        entry_type:
          type: string
          enum:
            - face
            - document
            - phone
            - email
            - ip_address
            - device_fingerprint
            - wallet_address
            - bank_account
            - country
            - user
            - business
            - key
          description: >-
            Què conté la llista: `face`, `document` (número de document),
            `phone`, `email`, `ip_address` (adreça o rang CIDR),
            `device_fingerprint`, `wallet_address`, `bank_account`, `country`
            (ISO 3166-1 alpha-3), `user` o `business` (el teu `vendor_data`), o
            `key` (qualsevol cadena). Decideix com es validen i es comparen els
            valors de les entrades.
        is_system:
          type: boolean
          description: >-
            `true` per a les llistes que Didit aprovisiona: una llista de
            bloqueig per tipus d'entrada (`face`, `document`, `phone`, `email`,
            `ip_address`, `device_fingerprint`, `wallet_address`,
            `bank_account`, `user`, `business`), la llista personalitzada **High
            Risk Countries** i les llistes d'admesos del sistema. Les llistes
            del sistema no es poden reanomenar, editar ni suprimir; pots afegir
            i suprimir les seves entrades.
        entry_count:
          type: integer
          minimum: 0
          description: Nombre d'entrades actualment a la llista.
        last_entry_added_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            Quan es va afegir l'entrada actual més recent. `null` per a una
            llista buida.
        created_at:
          type: string
          format: date-time
          description: Quan es va crear la llista.
        updated_at:
          type: string
          format: date-time
          description: Quan es va actualitzar la llista per darrera vegada.
  responses:
    RateLimitedWrite:
      description: >-
        S'ha superat el límit compartit d'escriptura de 300 sol·licituds per
        minut per clau d'API. Respecta `Retry-After` abans de reintentar.
      content:
        application/json:
          schema:
            type: object
            required:
              - detail
            properties:
              detail:
                type: string
          example:
            detail: >-
              Write request rate limit exceeded. You can make up to 300 requests
              per minute.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        La clau d'API de la teva aplicació, des de Developers -> API keys a la
        Business Console. La clau primària té accés complet. Una clau amb nom
        pot tenir l'abast limitat: cap, lectura o escriptura per recurs,
        limitada a determinats fluxos de treball o a sessions aprovades, a una
        llista d'adreces IP i a una data de caducitat. 401 significa que la clau
        és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap
        clau, que la clau no té accés a aquest recurs o acció, o que la
        sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una
        ruta de sessió significa que la sessió està fora dels fluxos de treball
        o estats de la clau. Una clau sense accés a fitxers multimèdia rep els
        URL d'imatge, vídeo i PDF com a null, i una clau sense permís
        d'escriptura de sessions rep els enllaços de sessió i els tokens com a
        null. Consulta https://docs.didit.me/console/api-keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.