{
  "SuccessCode": "SUCCESS",
  "Protocol": "AIXE",
  "Endpoint": "/aixe/research/create-search-contact",
  "Method": "POST",
  "ContentType": "application/json",
  "Title": "Create A Search Contact",
  "Description": "Company-discovery step. Create one person associated with the selected search and place that person in the individual-research queue with status Waiting For Research. The search moves to Discovering Contacts, or back to Researching Contacts if discovery had already been completed. Call once for every distinct person found. This endpoint records who the person is; phone numbers, emails, profiles, and other methods belong in contact-detail endpoints. Legacy email and phone fields remain accepted for existing callers.",
  "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."
    },
    {
      "Name": "SearchRequestContactKey",
      "Type": "guid",
      "Required": false,
      "Description": "Optional caller-generated GUID used for safe retries. Reuse the same value when retrying the same person. If it already belongs to this search, the existing contact is returned without duplication; if it belongs elsewhere, the request is rejected."
    },
    {
      "Name": "SearchRequestContactFirstName",
      "Type": "string",
      "Required": false,
      "Description": "Person\u0027s first or given name, up to 300 characters. Omit or use null when unavailable."
    },
    {
      "Name": "SearchRequestContactLastName",
      "Type": "string",
      "Required": false,
      "Description": "Person\u0027s last or family name, up to 300 characters. Omit or use null when unavailable."
    },
    {
      "Name": "SearchRequestContactPosition",
      "Type": "string",
      "Required": false,
      "Description": "Person\u0027s title, role, department, or responsibility at the business, up to 300 characters. Example: Marketing Director."
    },
    {
      "Name": "SearchRequestContactCompanyName",
      "Type": "string",
      "Required": false,
      "Description": "Company name associated with this person, up to 300 characters. Omit when it is the same as the search company; the web interface falls back to the search company."
    },
    {
      "Name": "SearchRequestContactNotes",
      "Type": "string",
      "Required": false,
      "Description": "Person-level context useful during later focused research, up to 50,000 characters. Do not place individual email addresses, phone numbers, or profiles here; save those as contact details."
    },
    {
      "Name": "SearchRequestContactSourceUrl",
      "Type": "string",
      "Required": false,
      "Description": "Optional source URL establishing that this person is associated with the business, up to 2,048 characters. This is evidence for the person record, not a replacement for sources on individual contact details."
    },
    {
      "Name": "SearchRequestContactEmailAddress",
      "Type": "string",
      "Required": false,
      "Description": "Legacy compatibility field for existing callers. New research workflows should use add-contact-detail or ContactDetails on complete-contact-research."
    },
    {
      "Name": "SearchRequestContactPhoneNumber",
      "Type": "string",
      "Required": false,
      "Description": "Legacy compatibility field for existing callers. New research workflows should use add-contact-detail or ContactDetails on complete-contact-research."
    }
  ],
  "Output": "Data fields: SearchRequestKey identifies the parent search; SearchRequestContactKey identifies the saved person and is reused by every later person-level endpoint; SearchRequestContactResearchStatus reports the person\u0027s queue state. A retry with the same caller-supplied contact key returns this same record without duplication.",
  "OperationalGuidance": [
    "Focus this phase on identifying people rather than deeply researching each person.",
    "Save each distinct person separately so claim-next-contact can issue one focused work item at a time.",
    "After the company-level list is finished, call complete-contact-discovery exactly once; repeating it is safe."
  ],
  "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"
  ]
}