For companies · API
Connect AVOCO to your own software
Your hiring system, app or website can send a voice recording to AVOCO and get the person's result back by itself, with no one opening the site. You don't need this to use AVOCO: everything also works right here in the browser.
How to start
- 1
Create a company workspace
Your company's space on AVOCO. Every recording your software sends lands there, in a group called "API".
- 2
Create an API key
A workspace admin creates it under Settings → API access. It is shown only once: keep it somewhere safe.
- 3
Hand the key to your developer
Along with a link to this page. The technical guide below is all they need: two requests.
What comes back for each person
- The eight personality types, each scored from 0 to 100
- The fourteen emotional scales, unless your workspace hides them
- The fields of work that fit the person best
The full written report stays in your workspace, where your team reads it.
Consent comes first
Send only recordings of people who agreed to the analysis. Your software confirms their consent with every recording.
For developers
Technical guide
Two calls: send a recording, then read the result about a minute later. Create an API key in your workspace (Settings → API access; admins only) and send it with every request. Keep it on your server, never in a browser or a mobile app.
Authorization: Bearer avk_your_key1. Send a recording
POST /api/public/v1/analyses, multipart/form-data. The file must hold 30 seconds to 5 minutes of one person speaking, as wav, mp3, m4a, ogg or opus, up to 4 MB (16 kHz mono WAV fits about 2 minutes; compressed formats fit the full 5). consent=true is required: it is your statement that the recorded person agreed to the analysis. Recordings appear in your workspace in a group called "API".
curl -X POST https://www.avocousa.us/api/public/v1/analyses \
-H "Authorization: Bearer $AVOCO_KEY" \
-F file=@interview.m4a \
-F name="Dana Lee" \
-F consent=true
202 {"id":"3f0e6c0e-…","status":"processing"}2. Read the result
GET /api/public/v1/analyses/:id. Ask every 5 to 10 seconds until status is completed or failed. A key only ever sees analyses from its own workspace.
curl https://www.avocousa.us/api/public/v1/analyses/3f0e6c0e-… -H "Authorization: Bearer $AVOCO_KEY"
200 {
"id": "3f0e6c0e-…",
"status": "completed",
"name": "Dana Lee",
"created_at": "2026-09-21T10:00:00.000Z",
"completed_at": "2026-09-21T10:00:41.000Z",
"psytype": [{ "key": "analyst", "label": "Analyst", "value": 56.4, "zone": "leading" }, …],
"emostate": [{ "key": "ability_to_attract", "label": "Attractiveness", "value": 76 }, …],
"best_fit": [{ "field": "research", "sector": "tech", "score": 48.3, "personality_score": 42.8, "state_score": 64.7 }, …],
"error": null
}psytype: eight personality types, 0 to 100, highest first. Zones: 50 and upleading, 30 to 49.9active, below 30background.emostate: fourteen emotional scales, 0 to 100.nullwhen your workspace hides emotional state.best_fit: this platform's fit score for 25 fields of work, best first.scoreis three quarterspersonality_score(from the types) and one quarterstate_score(from the emotional scales that work leans on;nullwhen emotional state is hidden, and thenscoreequalspersonality_score). Fields: leadership, entrepreneurship, operations, projects, finance, consulting, sales, service, marketing, stage, hr, teaching, counselling, healthcare, social, research, it, data, quality, law, arts, design, admin, hospitality, safety.error:analysis_failed(usually audio too short, too quiet or an unsupported format) ortimeout.
Errors
Always JSON: {"error":"<code>","message":"…"}
400 bad_request: no file, file over 4 MB, orconsentmissing401 unauthorized: API key missing or wrong404 not_found: no such analysis in your workspace429 limit_reached: your workspace's monthly limit is used up502 upstream_error: the analysis service is unavailable; try again later