Search and review results from your assistant or the API
Start a search, wait for it, read why a match fits, add your own people, and sort the results into lists and saved filters, from an AI assistant or the API.
Everything on this page finds people and sorts them. That's all. Nothing here sends an email. Not one thing. You can do all of it from an AI assistant such as Claude Code, or from the API with a key.
Two words first. The API is a web address your own code calls with a key instead of a password. The MCP server is the same thing shaped for AI assistants, and each job it can do is a tool, like recruit_search. Each job below lists both: the API route first, then the tool.
Start a search and wait for it
The first search runs in the background. You start it. Then you check on it, as often as you like, until it's done.
| Job | API | Tool |
|---|---|---|
| Start the first search | POST /v1/finder/searches/first | recruit_start_first_search |
| Check on a search | GET /v1/finder/searches/{id} | recruit_search_status |
| Search a topic, a rival or a channel | POST /v1/finder/searches | recruit_search |
| Find more matches | POST /v1/finder/searches/more | recruit_find_more_matches |
| Turn the weekly search on or off | POST /v1/finder/searches/weekly | recruit_set_weekly_search |
| See the latest search and when the next weekly one runs | GET /v1/finder/latest-search | recruit_search_status |
| Name your best affiliates as examples | POST /v1/finder/searches/examples | recruit_set_example_affiliates |
The first search is free. You get five starts in ten minutes for one account, and that counts every way in: the app, the API, an assistant or a script. One budget. Yes. If a first search already ran, the call hands that search back and starts nothing, so a script that retries by mistake never starts two. To start again after one failed, send retry: true.
Checking on a search has a long-poll. Send wait_seconds (up to 25) and the server holds your call until something changes or the time runs out. One call waits. Done. It counts as one request against your limit. A finished search answers at once. Nothing to wait for. Nothing at all.
curl "https://api.affiliaterail.com/v1/finder/searches/fsc_123?wait_seconds=25" \
-H "Authorization: Bearer $RECRUIT_KEY"While a first search runs, the answer lists each channel with its own count. You can say "38 found so far" instead of a bare "running", which tells the founder almost nothing about how it is going. Useful. An assistant gets the same facts as one plain sentence, then a short list of what to do next and why. While it waits, that list points at work that doesn't need the search, like setting your offer.
Find more matches picks the one search the app's button would pick. That's a nearby topic nobody has searched, or a similar brand that isn't a rival. It costs one search, the same as any other search you start yourself. An assistant shows you what it will search and your balance after, then waits for your yes. Nothing left? It says so. No charge.
The weekly search is a switch on the brand. You can turn it on for a plan that can't search right now. The answer says can_run: false in that case, so you know nothing will run until the plan can. Nobody is surprised later.
The latest search is what the search banner in the app shows. That's the newest search, the last first or weekly one that finished, and when the next weekly one runs. That date is there only when the search will really run. Otherwise weekly_off_because says why. Maybe no search has finished yet, the plan can't search right now, or someone turned the brand's weekly switch off in the app.
Example affiliates are up to five of your best sellers today. Each is a link: a YouTube channel, a profile, a site, a newsletter or a podcast. A search for people like them starts from these, so pick the ones whose audience you would most like more of. Free. A new pick replaces the old one. They don't keep anyone out of your results: add your existing affiliates as exclusions for that.
Read why a match fits
GET /v1/finder/prospects/{id} and recruit_affiliate return a why_fits section:
- score and fit: the number out of 100 and its label, like Strong fit.
- parts: the four things the score is made of, each with its points, its maximum and a sentence on why.
- chips: up to three short reasons, like "Works with a rival", each with the page that proves it.
- evidence: the pages the score rests on, with the rivals they name.
A YouTube channel shows no score of ours, the same as in the app. Titles and snippets in the evidence are text from other people's sites. An assistant treats them as data to read, never as instructions.
Ask in plain words
POST /v1/finder/ask and recruit_ask turn a sentence such as "UK bloggers who write about baby sleep" into filters and read the first matches. It's free. It starts no search. Nothing is saved either. If fewer than ten match, it names a topic you can search to find more.
Add your own people
| Job | API | Tool |
|---|---|---|
| Add a list of links | POST /v1/finder/imports/prospects | recruit_add_affiliates |
| Import your customers | POST /v1/finder/imports/customers | recruit_import_customers |
| Check your customers against the matches | POST /v1/finder/customers/match | recruit_match_customers |
| Change how many customers are proposed | POST /v1/finder/customers/propose | recruit_propose_customers |
Send dry_run: true to add a list first and see the counts: how many are new, how many you already have, how many links weren't usable. Nothing is written and nothing is spent. When you add for real, each new person can use one email lookup if your plan can find emails, so do the dry run first. An assistant's card is the dry run.
A customer list is read, and nothing else happens with it beyond the matching described here: no lookups, no emails, nothing sent anywhere. No lookups, no emails. People who are already affiliates, or who asked to be removed, are skipped. A YouTube handle in a list is counted but not looked up, because that lookup costs us money.
Notes, tags and owners
| Job | API | Tool |
|---|---|---|
| Add a note, set tags, set a follow-up date | POST /v1/finder/prospects/{id} and POST /v1/finder/prospects/{id}/notes | recruit_annotate |
| Read the notes | GET /v1/finder/prospects/{id}/notes | recruit_affiliate_notes |
| Edit a note | POST /v1/finder/prospects/{id}/notes/{note_id} | recruit_edit_note |
| Delete a note | DELETE /v1/finder/prospects/{id}/notes/{note_id} | recruit_delete_note |
| Give people to a teammate | POST /v1/finder/assignments | recruit_assign_affiliates |
A key has no person behind it. A note written through a key is signed by whoever made the key, or by the account owner if they've left.
Do not contact, and already ours
Do not contact means no campaign will email that person. POST /v1/finder/prospects/{id}/do-not-contact and recruit_set_do_not_contact mark someone, with a reason, or lift the mark.
Already ours is for someone who already works with you as an affiliate. They move to your existing affiliates. They stay out of every search. They stay out of every send, too, until you undo it. POST /v1/finder/already-ours and recruit_mark_already_ours mark them. POST /v1/finder/already-ours/undo and recruit_undo_already_ours take back only the marks you just made.
Lists and saved filters
A list is a named group of saved people. A saved filter, also called a segment, is a search you keep, so who is in it changes as your saved people do.
| Job | API | Tool |
|---|---|---|
| Rename a list | POST /v1/finder/lists/{id} | recruit_rename_list |
| Delete a list | DELETE /v1/finder/lists/{id} | recruit_delete_list |
| See your saved filters | GET /v1/finder/segments | recruit_segments |
| See who a saved filter holds | GET /v1/finder/segments/{id}/members | recruit_segment_members |
| Make a saved filter | POST /v1/finder/segments | recruit_create_segment |
| Change a saved filter | POST /v1/finder/segments/{id} | recruit_update_segment |
| Delete a saved filter | DELETE /v1/finder/segments/{id} | recruit_delete_segment |
Deleting a list or a saved filter can't be undone. So an assistant shows a card first, saying exactly what will go and what will stay, and waits for your yes. Deleting a list leaves the people on it. Only the list goes. Deleting a saved filter deletes the filter only.
What an assistant asks you first
An assistant shows you a card before it changes anything. The card says what will change and what it costs. It then waits for your yes before it goes ahead.
- Costs a search: find more matches.
- Can use email lookups: add your own people.
- Can't be undone: deleting a list, a saved filter or a note.
- Free, and says so: everything else on this page.
Test keys only change sample data. A test key that asks to start a search gets a pretend one, stored nowhere, so nothing is spent and nothing real is touched.
Was this page helpful?