# Fetch Lockbox Directory

Retrieves the catalog of valid lockbox destinations known to DPN, paginated. Use this endpoint to pre-validate or pre-match payee destinations before submitting a payment file, at payee onboarding time to anchor a payee to a known lockbox, and on a periodic schedule (weekly or on demand) to keep a cached copy fresh. Unlike the other DPN endpoints, this endpoint authenticates through an issued apiKey and operates on a separate rate-limit budget.

Endpoint: GET /lockbox
Security: securitySchemas.oidcEnforcement

## Security:

  - `securitySchemas.oidcEnforcement` (unknown)
    oauth2

## Query parameters:

  - `PageNumber` (integer)
    1-based page index used to retrieve a specific page of the directory. Increment across successive calls to walk the full catalog, or use the URLs returned in the links array of a prior response.

  - `PageSize` (integer)
    Number of lockbox records to return per page. Choose a value that balances round-trip volume against per-response payload size; the sample collection uses 20.

  - `IncludeInactive` (boolean)
    includes lockboxes with a status of Inactive in response.

  - `IncludeDeleted` (boolean)
    Includes lockboxes that have been soft-deleted in response.

  - `CustomerName` (string)
    Filter response to only include lockboxes belonging to the identified Customer.

  - `Location` (string)
    The Location that the lockbox which is being added belongs to.

  - `SysId` (string)
    Filter response to only include lockboxes belonging to the identified System.

## Header parameters:

  - `apiKey` (string, required)
    Identifier issued by Deluxe during onboarding that authenticates the caller to the Deluxe Lockbox Directory (DDN) service. It is separate from the businessPartner used on the payment endpoints and must be treated as a sensitive secret. Rotate through your Account Manager if exposure is suspected.

## Response 200 fields (application/json):

  - `value` (array, required)
    Array of lockbox records for the requested page. Each element describes a single lockbox destination that can be used to route a payment.

  - `value.directoryId` (string, required)
    Stable unique identifier for the lockbox record.Persist this on the caller side to anchor payees to a specific lockbox in your own systems.
    Example: c52dcea6-2519-4bf4-b2ed-9fb16567afd3

  - `value.system` (object, required)
    The system associated with the lockbox.

  - `value.system.customerName` (string, required)
    Name of customer in DDN Directory.
    Example: DPNTestCustomer

  - `value.system.locationName` (string, required)
    Name of the location configured in the DPN Directory.
    Example: DPNLocation

  - `value.system.sysId` (string, required)
    Name of the system configured in the DPN Directory, eg IL.
    Example: VICPers

  - `value.address` (object, required)
    Structured postal address for the lockbox destination.

  - `value.address.createdAt` (string, required)
    Timestamp when the lockbox record was first created in the directory. ISO 8601 format.
    Example: 2024-02-22T16:54:27.89585Z

  - `value.address.poBox` (integer)
    PO Box number for the lockbox, when applicable. Present as a numeric value.
    Example: 12200

  - `value.address.street1` (string, required)
    First line of the postal address. Typically the PO Box or street line used for delivery.
    Example: PO Box 489

  - `value.address.street2` (string)
    Second line of the postal address, when a single line is insufficient.

  - `value.address.city` (string, required)
    City portion of the postal address.
    Example: Carol Stream

  - `value.address.state` (string, required)
    Two-letter US state code portion of the postal address.
    Example: IL

  - `value.address.zip` (string, required)
    ZIP or ZIP+4 code for the postal address.
    Example: 60197-0489

  - `value.providerId` (integer, required)
    Unique identifier assigned by the lockbox provider for the  lockbox.
    Example: 12200

  - `value.isActive` (boolean)
    The active status of the lockbox.
    Example: true

  - `value.isDeleted` (boolean)
    The deleted status of the lockbox.
    Example: false

  - `value.createdAt` (string)
    The date the lockbox was created.
    Example: 2024-04-11T19:36:48.341053Z

  - `value.mailStop` (string)
    Optional mail-stop qualifier associated with the lockbox address. Populated only when the destination requires an internal routing marker in addition to the postal address.

  - `value.agreement` (string)
    Defines how strictly DPN should match payments to the lockbox address.
    Example: Var

  - `value.maxBatchSize` (integer)
    Maximum number of items the lockbox can process in a single batch
    Example: 50

## Response 400:

  - `400` (unknown)
    Bad Request

## Response 400 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 401:

  - `401` (unknown)
    Unauthorized

## Response 401 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 403:

  - `403` (unknown)
    Forbidden

## Response 403 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 404:

  - `404` (unknown)
    Not Found

## Response 404 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 405:

  - `405` (unknown)
    Method Not Allowed

## Response 405 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 406:

  - `406` (unknown)
    Not Acceptable

## Response 406 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 408:

  - `408` (unknown)
    Connection Timeout

## Response 408 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 415:

  - `415` (unknown)
    Unsupported Media Type

## Response 415 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 429:

  - `429` (unknown)
    Too Many Requests

## Response 429 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 500:

  - `500` (unknown)
    Internal Server Error

## Response 500 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 501:

  - `501` (unknown)
    Not Implemented

## Response 501 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 503:

  - `503` (unknown)
    Service Unavailable

## Response 503 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 504:

  - `504` (unknown)
    Gateway Timeout

## Response 504 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

