Sync athletes and teams from your system

When your roster lives in another system, a scheduled job can push it to Vitruve so nobody keeps two lists by hand. Your system stays the source of truth; Vitruve follows it.

Keep a mappingCopy Anchor Link

Store the Vitruve id next to each of your own records when you create it: athletes, teams and the coaches you assign. Vitruve has no field for your ids, so the mapping is what lets later runs update instead of duplicate.

For a first run against an organization that already has athletes, match them by email with GET /athletes?search=<email> before creating anyone.

AthletesCopy Anchor Link

Some athletes manage their own profile:

• An athlete who claimed their own Vitruve account can't be updated: PATCH answers 403. Skip them, or stop syncing their profile fields.
• Once an athlete is verified, only they can change birthDate and dominantSide. Leave those out of the body.
• Deleting a profile your organization manages deletes it for good, with its training history. A verified athlete, or one another organization also holds, is only removed from your organization. Deleting is the one call to double-check before automating.

An email that belongs to another Vitruve user answers 409. The athlete probably has an account already: invite them from the app instead.

TeamsCopy Anchor Link

Create teams with POST /teams. On each run, send the full list of a team's athletes with PATCH /teams/{id} and athleteIds: it replaces the team's athletes in one call. Staff members the app added to the team are kept.

To change one membership at a time, use PUT /teams/{id}/athletes/{athleteId} and DELETE /teams/{id}/athletes/{athleteId} instead.

Coach assignmentsCopy Anchor Link

PUT /coaches/{id}/athletes with athleteIds sets exactly which athletes a coach sees. Every other athlete is unassigned from them, and athletes who join later are assigned by default. Coaches themselves are invited from the app: the API assigns existing coaches, it doesn't create them.

Make the job safe to rerunCopy Anchor Link

• Order the calls: athletes first, then teams, then coach assignments, so every id you send already exists.
• Send an Idempotency-Key on every POST, derived from your own record, such as roster-athlete-8812. A retry after a timeout then returns the first answer instead of creating twice. PATCH, PUT and DELETE can be repeated as they are.
• Stop on 403. It means the plan doesn't allow the write, or a limit such as the number of athletes was reached. Retrying won't change it.
• Stay under the rate limit: writes count towards the same 30 requests per minute as reads.

Every field, rule and error of these calls is in Organization and people.