Unlock Records

Unlock email or phone data for one or more records returned by Search Records. Unlocking deducts credits from your wallet. Records you've already unlocked are skipped (no double-charge).

Endpoint

Method: POST Path: /external/unlock/ Full URL: https://app.ecoreservice.com/backend/api/v1/external/unlock/ Auth: Authorization: Token YOUR_API_TOKEN — see Authentication

Request Body

Content-Type: application/json

Field	Type	Required	Description
uuids	array of strings	Yes	One or more record UUIDs (from a Search response)
unlock_type	string	Yes	"email" or "phone"

Credit Costs

Unlock Type	Cost	Condition
Email	1 credit	Per record
Phone	5 credits	Per record that has phone data on file
Phone	1 credit	Per record with no phone data (still locks a slot in your account)
Already owned	0 credits	Records you've previously unlocked are skipped silently

See Credit Costs for the full pricing table.

Example Request

curl -X POST \
  "https://app.ecoreservice.com/backend/api/v1/external/unlock/" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "uuids": ["a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d", "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e"],
    "unlock_type": "email"
  }'

Successful Response — 200 OK

{
  "success": true,
  "message": "Records unlocked successfully.",
  "unlocked": 2,
  "credits_charged": 2,
  "wallet_balance": 498
}

Response Fields

Field	Type	Description
success	boolean	Always true on 200 OK
message	string	Human-readable confirmation
unlocked	integer	Number of records unlocked by this call (excludes already-owned)
credits_charged	integer	Total credits deducted from the wallet for this call
wallet_balance	integer	Wallet balance remaining after the deduction

After a successful unlock, calling Search Records again with the same filters returns the unlocked records with contact_email (or contact_direct_phone / contact_mobile_phone) populated and the corresponding is_email_unlocked / is_phone_unlocked flag flipped to true.

Error Responses

HTTP	When	Body
400	Missing uuids, missing or invalid unlock_type	{"error": "..."}
401	Missing or invalid token	{"detail": "Invalid token."}
402	Insufficient credits to unlock the requested records	{"error": "Insufficient credits.", "required": N, "balance": M}
404	None of the supplied UUIDs exist	{"error": "No matching records found."}

See Error Codes for the full list.