{
  "SuccessCode": "SUCCESS",
  "Protocol": "AIXE",
  "Endpoint": "/aixe/research/claim-next-contact",
  "Method": "POST",
  "ContentType": "application/json",
  "Title": "Claim Next Contact",
  "Description": "Atomically claim one person who is Waiting For Research, oldest first, and return everything required for a focused research pass. The response includes the person, company, business address, original customer instructions, person notes and source, a temporary claim key, and its expiration. Expired Researching claims are automatically eligible for recovery. Simultaneous workers cannot successfully claim the same active person. When no person is available, Contact is null and the response explains whether other claims or failures remain.",
  "Authentication": "Use the capability credential described in InputFields. Research mutation endpoints use unguessable public record keys as scoped capability credentials; never substitute numeric database IDs.",
  "RequestRules": [
    "Send one JSON object using the exact case-sensitive field names in InputFields.",
    "Required means the property must be present and valid. Omit an optional property when its value is unknown unless that field description explicitly permits null or empty text.",
    "GUID values are JSON strings in standard GUID format. Never send internal numeric database IDs.",
    "A successful HTTP response is not enough by itself; inspect the response body\u0027s SuccessCode."
  ],
  "InputFields": [
    {
      "Name": "SearchRequestKey",
      "Type": "guid",
      "Required": true,
      "Description": "The selected search request\u0027s public GUID."
    }
  ],
  "Output": "Data fields: Contact is null when no person can be claimed; otherwise it is the complete focused-work object. SearchRequestKey identifies the parent search. SearchRequestCompanyName and SearchRequestCompanyAddress keep the correct business in context. SearchRequestContent repeats the customer\u0027s original instructions. SearchRequestContactKey identifies the person. The name, position, company, notes, and source fields describe that person. SearchRequestContactResearchStatus is Researching after the claim. SearchRequestContactResearchClaimKey is the temporary exclusive completion credential. SearchRequestContactResearchClaimExpiration is its UTC deadline. RemainingUnclaimedContacts counts waiting or already-expired work. With a null Contact, ContactsCurrentlyClaimed counts other live leases and FailedContacts counts terminal failures.",
  "OperationalGuidance": [
    "Call complete-contact-discovery before the first claim.",
    "Research only the single returned person while keeping the supplied company and original request in context.",
    "Finish with complete-contact-research, or release/fail the claim with set-contact-research-status.",
    "Do not reuse a claim key for another person. If the lease expires, claim the person again and use the newly returned key."
  ],
  "ResponseEnvelope": [
    {
      "Name": "SuccessCode",
      "Type": "string",
      "Required": true,
      "Description": "SUCCESS means the operation completed. Any other value is a machine-readable error code and means the requested change or read did not complete as described."
    },
    {
      "Name": "Message",
      "Type": "string",
      "Required": true,
      "Description": "Human-readable outcome and next-step context. Use SuccessCode for program decisions."
    },
    {
      "Name": "Data",
      "Type": "object|null",
      "Required": false,
      "Description": "Endpoint-specific result described by Output. Error responses may omit this property or return null."
    },
    {
      "Name": "PersonAuthenticationTokenExpiration",
      "Type": "datetime|null",
      "Required": false,
      "Description": "Returned by authenticated customer calls after a successful sliding-session refresh. Research endpoints do not use or return it."
    }
  ],
  "Errors": [
    "VALIDATION_FAILED",
    "AUTHENTICATION_REQUIRED",
    "AUTHENTICATION_FAILED",
    "NOT_FOUND",
    "ACCESS_DENIED",
    "ACCOUNT_EXISTS",
    "CONFLICT",
    "NOT_SUPPORTED",
    "REJECTED",
    "RATE_LIMITED",
    "INSUFFICIENT_CREDITS",
    "CONFIGURATION_REQUIRED",
    "FAILED"
  ]
}