CRM (FreshSales) integration with Blackbaud

Bilguun Zorigtbaatar
Bilguun Zorigtbaatar
Name Dropper Facilitator 1
in Education Management APIs

I’m working on automating our student‐creation workflow by integrating Freshsales Suite Pro CRM with Blackbaud Education Management’s Enrollment Management API via webhooks. Here’s where we are:

Freshsales side:

We collect new‐student data (first/last name, personal email) in Freshsales.

When a contact is marked “Enrolled,” a Suite Pro workflow fires a webhook with that payload.

Institutional email mapping:

We provision each student’s official address (jane.doe@student.edu) in our directory before creating their Blackbaud record.

Our middleware enriches the webhook payload with the institutional email.

Blackbaud setup:

We have a developer account, SKY API app, and OAuth2 (Auth Code + PKCE) configured with scopes granted.

What I’m looking for:

Endpoint URL(s): Which exact Enrollment Management API endpoint(s) should I call to create and update candidate (student) records?

Request payload: What JSON schema and required fields (e.g. firstName, lastName, email, programCode, etc.) must be included in the POST body?

Path/query parameters: Are there additional parameters (like schoolId, campusCode, termId) that belong in the URL or query string?

Scopes & permissions: Which OAuth scopes and application permissions are required to allow candidate creation and updates?

Examples: Can you share sample request/response payloads or code snippets for creating a candidate?

Best practices: Any guidance on idempotent creation (avoiding duplicates), error‐handling patterns, or rate‐limit recommendations?

If you’ve built a similar webhook‐driven integration or have sample code, I’d greatly appreciate your guidance. Thank you!

Comments

  • Stephen Boyle
    Stephen Boyle Blackbaud Employee
    Tenth Anniversary Kudos 5 Name Dropper Participant

    @Bilguun Zorigtbaatar
    Here is the starting point for API endpoint reference for Education.
    Here is the documentation for our APIs, including auth flow (with sample code).
    Some of what you ask for is in the docs and each endpoint describes the specifics in its swagger doc/endpoint description.

    For your questions on exact endpoints, that will depend on what you trying to do. But adding a person starts with the POST User create in the School API (everyone is a user) and then can require other endpoints (e.g. if that person will be a candidate or a teacher or a student). If you are working with a school, they can help you understand where they expect the record to show in the product, which then will determine what endpoints would apply. If this is happening after enrollment, the school may not need them to show in Admission/Enrollment Mgmt but expect to see them in the SIS - so it depends.

    I'm happy to help with where things are in the APIs. The community here can help there too, and help with best practice strategies, as well.

  • Bilguun Zorigtbaatar
    Bilguun Zorigtbaatar
    Name Dropper Facilitator 1

    @Stephen Boyle
    Thank you for the response.
    I will try to explain what our school is trying to achieve.

    Goal: Eliminate all manual student‐record entry by having Freshsales “Enrolled” → webhook → Blackbaud API create the user & candidate in one seamless flow.

    Flow:

    Freshsales: Prospect marked “Enrolled” fires a Suite Pro webhook carrying first/last name, personal email, etc.

    Middleware: Receives that JSON, looks up or generates the institutional address (jane.doe@student.edu), and handles OAuth2 to Blackbaud.

    Blackbaud API Calls:

    POST /school/v1/users to create the user record (everyone in BB is a “user”) with firstName, lastName, email, etc.

    POST /enrollment/v1/candidates (or the equivalent Enrollment endpoint) to create their candidate profile, passing required fields like schoolId, programCode, termId, plus the newly created user’s ID.

    Idempotency & Updates: If the user already exists (same email), use PATCH on /school/v1/users/{userId} and then upsert the candidate record.

    What we need:

    Exact endpoint paths & HTTP methods for both “create user” and “create candidate.”

    The minimal JSON schema for each (required properties & nesting).

    Which query/path parameters (e.g. schoolId in the URL) and OAuth scopes (user.write, enrollment.write, etc.) are mandatory.

    Any sample request/response snippets or best-practice tips for avoiding duplicates and handling errors.

    With that clear, end-to-end picture, we can plug in the right URLs and payloads and have Freshsales push brand-new students straight into our BB SIS—no more manual entry.

    To be honest, I’m not a back-end developer—I’m a front-end developer with some back-end testing experience. After going through all these articles on my own, I’m kind of lost. If someone could guide me on this, our school would be happy to have them for the duration of the project.

Categories