{"Name":"Find The Contact","Version":"1.0","Description":"Save business contact research requests and read their results. Research uses a two-phase workflow: first identify people at the requested business, then claim and deeply research one person at a time. New searches require available account credits; recharge on the website by creating an invoice.","Authentication":"Log in with Email and Password. Send PersonAuthenticationToken in customer action bodies; idle expiry is 15 minutes. Research credentials are specified separately in each endpoint's discovery. Password changes and recovery are website-only.","ResearchWorkflow":["1. Read get-waiting-searches and choose one business search.","2. Discover people at that business and call create-search-contact once per person.","3. Call complete-contact-discovery after the current person list is saved.","4. Repeatedly call claim-next-contact. Deeply research only the single returned person.","5. Call complete-contact-research with that person's free-form details, or set-contact-research-status to release/fail the attempt.","6. Continue until claim-next-contact returns Contact null. Use list-search-contacts to inspect failures or progress; use add-contact-detail for later findings."],"DiscoveryInstruction":"Before calling any endpoint, GET the endpoint's Discovery URL ending in /?. It defines every input, output, workflow rule, credential, status transition, limit, and retry behavior for that operation.","ProtocolReference":{"Protocol":"AIXE","Inventor":"Gregory Oglethorpe","Home":"http://aixeprotocol.com/","Usage":"http://aixeprotocol.com/usage/?","Specification":"http://aixeprotocol.com/whitepaper/full-spec.html"},"Endpoints":[{"Path":"/aixe/account/register","Method":"POST","Title":"Create An Account","Description":"Create a person profile and initial password. Existing passwords cannot be changed through AIXE.","Group":"Account","AccessType":"Public","Status":"Active","Discovery":"/aixe/account/register/?"},{"Path":"/aixe/account/login","Method":"POST","Title":"Log In","Description":"Authenticate with email and password to receive an opaque 15-minute token.","Group":"Account","AccessType":"Public","Status":"Active","Discovery":"/aixe/account/login/?"},{"Path":"/aixe/account/get-profile","Method":"POST","Title":"Get My Profile","Description":"Read the authenticated customer's profile.","Group":"Account","AccessType":"Public","Status":"Active","Discovery":"/aixe/account/get-profile/?"},{"Path":"/aixe/account/update-profile","Method":"POST","Title":"Update My Profile","Description":"Update supplied profile fields for the authenticated customer. Password fields are rejected.","Group":"Account","AccessType":"Public","Status":"Active","Discovery":"/aixe/account/update-profile/?"},{"Path":"/aixe/account/logout","Method":"POST","Title":"Log Out","Description":"Invalidate the current AI authentication token.","Group":"Account","AccessType":"Public","Status":"Active","Discovery":"/aixe/account/logout/?"},{"Path":"/aixe/searches/create-search","Method":"POST","Title":"Create A Search","Description":"Save a new request with status Waiting For Research and deduct the configured Search.CreditCost from available credits. Insufficient credits returns INSUFFICIENT_CREDITS without saving a request. Reuse the same optional SearchRequestKey when retrying a submission to avoid duplicate requests and charges. Research runs separately.","Group":"Searches","AccessType":"Public","Status":"Active","Discovery":"/aixe/searches/create-search/?"},{"Path":"/aixe/searches/update-search","Method":"POST","Title":"Update My Search","Description":"Update supplied intake fields on an owned request only while its status is exactly Waiting For Research. Other statuses return REJECTED without modifying the request. Preserves status and contacts; costs no credits.","Group":"Searches","AccessType":"Public","Status":"Active","Discovery":"/aixe/searches/update-search/?"},{"Path":"/aixe/searches/list-searches","Method":"POST","Title":"List My Searches","Description":"Read a bounded page of owned search summaries, newest first.","Group":"Searches","AccessType":"Public","Status":"Active","Discovery":"/aixe/searches/list-searches/?"},{"Path":"/aixe/searches/get-search","Method":"POST","Title":"Get My Search","Description":"Read the selected owned request. Fetch contacts separately with list-contacts.","Group":"Searches","AccessType":"Public","Status":"Active","Discovery":"/aixe/searches/get-search/?"},{"Path":"/aixe/searches/list-contacts","Method":"POST","Title":"List My Search Contacts","Description":"Read a bounded page of contacts belonging to an owned request, oldest first. All contact content fields are optional; a contact may be blank.","Group":"Searches","AccessType":"Public","Status":"Active","Discovery":"/aixe/searches/list-contacts/?"},{"Path":"/aixe/research/get-waiting-searches","Method":"POST","Title":"Get Waiting Searches","Description":"First step of company-level research. Read searches whose status is exactly Waiting For Research, oldest first. Each result contains the business identity, address, and customer's original instructions needed to discover people associated with the correct business. This endpoint is read-only: it does not claim or change a search. Use the privately supplied ResearchAccessKey only here. When processing changes the queue, restart at the first page rather than advancing a cursor over the changing result set.","Group":"Research","AccessType":"Public","Status":"Active","Discovery":"/aixe/research/get-waiting-searches/?"},{"Path":"/aixe/research/set-search-status","Method":"POST","Title":"Set Search Status","Description":"General-purpose search status override retained for existing research integrations. Possession of an existing SearchRequestKey authorizes the change. It saves the supplied string exactly, including case, spaces, or an empty value. Only the exact value Waiting For Research appears in get-waiting-searches. The dedicated contact-discovery and contact-research endpoints automatically manage normal workflow statuses, so do not use this endpoint between their normal steps unless intentionally overriding the overall search state.","Group":"Research","AccessType":"Public","Status":"Active","Discovery":"/aixe/research/set-search-status/?"},{"Path":"/aixe/research/create-search-contact","Method":"POST","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.","Group":"Research","AccessType":"Public","Status":"Active","Discovery":"/aixe/research/create-search-contact/?"},{"Path":"/aixe/research/complete-contact-discovery","Method":"POST","Title":"Complete Contact Discovery","Description":"Close the company-level person-discovery phase for one search. Call after all currently known people have been created. If people exist, the search moves to Researching Contacts and claim-next-contact becomes available. If none exist, the search moves to Completed — No Contacts Found. Repeating this call is safe. People may still be added later; a newly added person returns the search to Researching Contacts.","Group":"Research","AccessType":"Public","Status":"Active","Discovery":"/aixe/research/complete-contact-discovery/?"},{"Path":"/aixe/research/list-search-contacts","Method":"POST","Title":"List Research Contacts","Description":"Read a bounded, oldest-first page of people attached to one search for research monitoring and recovery. This endpoint does not claim, release, or modify anyone. Omit the status filter to see every person, or supply one exact server status to inspect a subset. Use claim-next-contact for normal work assignment instead of selecting an unclaimed person from this list yourself.","Group":"Research","AccessType":"Public","Status":"Active","Discovery":"/aixe/research/list-search-contacts/?"},{"Path":"/aixe/research/claim-next-contact","Method":"POST","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.","Group":"Research","AccessType":"Public","Status":"Active","Discovery":"/aixe/research/claim-next-contact/?"},{"Path":"/aixe/research/complete-contact-research","Method":"POST","Title":"Complete Contact Research","Description":"Finish one actively claimed person's focused research in a single transaction. Supply the contact key and current unexpired claim key returned by claim-next-contact. ContactDetails is the complete set found during this research pass and may contain zero to 100 entries. Each entry uses unrestricted free text for its type, so any current or future platform, directory, communication method, biography, or professional source can be represented. Details are saved, the person becomes Completed or Completed — No Contact Details Found, and the overall search completes automatically after every person reaches a terminal status. Retrying the same completed claim is idempotent and does not duplicate details.","Group":"Research","AccessType":"Public","Status":"Active","Discovery":"/aixe/research/complete-contact-research/?"},{"Path":"/aixe/research/add-contact-detail","Method":"POST","Title":"Add Contact Detail","Description":"Add one newly discovered detail to an existing person after or outside the normal completion batch. Use this for later findings rather than rerunning complete-contact-research. The detail type is unrestricted free text and does not control display behavior. A valid HTTP or HTTPS URL is clickable on the website; other supplied URL text is retained but not made executable.","Group":"Research","AccessType":"Public","Status":"Active","Discovery":"/aixe/research/add-contact-detail/?"},{"Path":"/aixe/research/set-contact-research-status","Method":"POST","Title":"Release Or Fail Contact Research","Description":"Handle an individual research attempt that cannot be completed normally. For an active Researching contact, provide its current claim key and set the status to Waiting For Research to release it for another worker, or Research Failed to record a terminal failure. A failed contact can later be reset to Waiting For Research using the search and contact keys without an active claim. Completed states must be produced by complete-contact-research. Overall search status is recalculated automatically.","Group":"Research","AccessType":"Public","Status":"Active","Discovery":"/aixe/research/set-contact-research-status/?"}]}