Deepdots Python SDK
Python SDK for the Deepdots API (the company was formerly called MagicFeedback).
Installation
pip install deepdots
The original distribution is still published and still works:
pip install magicfeedback
Naming
MagicFeedback was renamed Deepdots. Both sets of names work and refer to the same objects, so no existing code needs to change:
| Current name | Original name | |
|---|---|---|
| PyPI distribution | deepdots |
magicfeedback |
| Import package | deepdots_sdk |
magicfeedback_sdk |
| Client class | Deepdots |
MagicFeedback |
Distribution names are written lowercase throughout — that is the packaging
convention, and PyPI treats names case-insensitively anyway, so
pip install MagicFeedback keeps working for anyone who has it written that way.
deepdots_sdk re-exports magicfeedback_sdk module by module, and Deepdots
is the same class object as MagicFeedback — MagicFeedback is Deepdots is
True, so isinstance() checks and subclasses behave identically. Submodule
imports work under either name (from deepdots_sdk.api.feedback import FeedbackAPI). New code should prefer the Deepdots names.
Usage
from deepdots_sdk import Deepdots
# With an API user's email and password.
client = Deepdots("email", "password", auth_source="identity",
base_url="https://api.deepdots.com")
The original names remain fully supported:
from magicfeedback_sdk import MagicFeedback
client = MagicFeedback("email", "password")
Authentication
The client signs in through the API (POST /auth/token), which asks Identity
Platform for the token. The SDK no longer calls Identity Platform itself, so it
needs no Identity Platform key: the ip_key argument is ignored (with a
DeprecationWarning). The token lasts one hour; the client keeps the refresh
token the API returns.
The token is resolved from one of two sources, selected with auth_source:
"datastore"(default) — read the token cached in Google Cloud Datastore by theupdate-tokenjob (kindtoken-storage, emailrobot@magicfeedback.io, databaseshared). This avoids a sign-in on every use. If the cached token is missing, stale (older thantoken_max_age_min, default 50 min) or Datastore is unreachable, the client falls back to signing in withuser/password."identity"— always sign in withuser/password, with no Datastore lookup. Use it outside Deepdots' own Google Cloud projects, where the Datastore cache can't be read.
# Datastore-cached token (default), signing in as the fallback.
# email/password are only needed for the fallback.
client = MagicFeedback("email", "password")
# Tune the Datastore lookup (all optional; shown with their defaults):
client = MagicFeedback(
"email", "password",
auth_source="datastore",
gcp_project_id=None, # None => inferred from Application Default Credentials
datastore_database_id="shared",
token_kind="token-storage",
token_email="robot@magicfeedback.io",
token_max_age_min=50,
datastore_timeout_s=5.0, # cap the lookup so the fallback stays fast
)
# Always sign in with email and password:
client = MagicFeedback("email", "password", auth_source="identity")
A wrong email or password raises requests.HTTPError with a 401 (the same
for both, so the API does not tell which accounts exist); a disabled user is a
403, and too many failed attempts on the account a 429.
The Datastore lookup is bounded by datastore_timeout_s (default 5s): if the
cache is unreachable or the credentials are stale, the client falls back to
signing in within that budget instead of blocking on the Datastore client's
default ~60s retry deadline.
The Datastore path needs the google-cloud-datastore package (installed as a
dependency) and Google Application Default Credentials with read access to the
token entity (gcloud auth application-default login or
GOOGLE_APPLICATION_CREDENTIALS).
Helper methods:
client.refresh_token()— renew the token and update the auth header in place across all sub-API clients. Withauth_source="identity"it uses the refresh token (POST /auth/token/refresh), and signs in again if that was rejected; with"datastore"it re-reads the cache (signing in as the fallback). Useful for long-lived clients whose token has expired:client.crmcalls it by itself on a 401.client.auth.get_token_from_datastore(allow_stale=False)— read the cached token directly; returnsNonewhen missing, stale or unreachable.
API Reference
client.feedbacks
create(feedback)— creates a feedback viaPOST /feedbacks. The dict becomes the JSON body with your keys unchanged, so every field is top-level (the SDK only wraps a scalarvalueinto a list, see below, and adds a missingcompanyId/productId, see next). The SDK requiresname,type,identityandintegrationId(it raisesValueErrorbefore sending if one is missing).companyIdandproductIdare optional (since 1.0.25): when one is missing or empty (Noneor""),create()copies it from the integration, which it reads once perintegrationId(GET /integrations/{id}) and keeps for the life of the client (an integration without a company or product is read again on each call) — after moving an integration to another product, create a new client or passproductId. Non-empty values you pass are kept, and the copied values go into the request only, not into your dict. If you already sendproductId, keep sending the same value:external_iddeduplication matches company, product and integration, so a different product makes re-sent feedbacks new ones. The API can fill them from the integration too, but when your user can't read it, it files the feedback under your user's own company with no product; reading the integration in the SDK makes that case an error instead. If the integration has no company, or has no product and you don't passproductId, or belongs to another company than thecompanyIdyou pass,create()raisesValueError; if the API refuses the read (406 for an integration that doesn't exist, was deleted or deprecated, or your user can't see; 405 if your role can't read integrations), it raisesrequests.HTTPError. Nothing is created in either case, and passing both fields skips the lookup. Use theidentityof the integration the feedback belongs to: survey identities such asMAGICFORM,MAGICSURVEYandCSVanalyseanswers, while most others, such asGENERALandCUSTOM, analyse onlytext, and some accepted values are not analysed at all. Optional fields includetext,answers,metadata,metrics,crmContactIdand the source-system fieldsexternal_id,externalGeneratedAt,externalUpdatedAtandexternalUrl— see Feedback source-system fields. Keys are case-sensitive. A misspelled required key (e.g.integration_idinstead ofintegrationId) makes the SDK raiseValueError: Missing required field: integrationId; any other key the API does not accept is rejected with 422 and nothing is created — a misspelling such ascompany_idorexternalId, or a server-set field such asid,statusorcreatedAt. Whenexternal_idmatches an existing, non-deleted feedback of the same company, product and integration, the API returns that feedback unchanged (HTTP 200, nothing written) instead of creating a duplicate.get(filter=None)— lists feedback items. To find the feedback an SDK session became, filter on thesessionIdthatPOST /sdk/feedbackreturned:get(filter={"where": {"sdkSessionId": session_id}, "order": ["createdAt DESC"]}). Set only on feedbacks created after the field shipped. Since 2026-10-07 a session that closes again updates the feedback it already has, so a session normally maps to one feedback. A session can still have two (one that closed twice between 2026-09-30 and 2026-10-07, or whose first feedback was deleted), so keep theorderand take the first result.get_id(feedback_id, filter=None)— retrieves a specific feedback item.update(feedback_id, feedback)—PATCH /feedbacks/{id}with only the fields you pass; returns{}(the API answers 204).external_id,type,identity,integrationId,productId,profileanddatacannot be changed (422), so never PATCH back a whole object read fromget_id(). The change is saved immediately, but charts and reports pick up changes to the date,text,answers,metricsormetadataonly when the feedback is re-analysed: include"status": "REGISTERED"in the same call to queue a full re-analysis — read what that does at the end of Feedback source-system fields first.update()needs an API user whose role may update feedback (otherwise 405).update_metadata_batch(items, mode=None)— merges metadata into many feedbacks in one request and triggers re-analysis for each, so the change propagates through the analysis pipeline to BigQuery (insight.metadata) and the metadata table.itemsis a list of{"feedbackId": ..., "metadata": [{"name": ..., "values": [...]}]}; each metadata entry may use the SDK-native{"key": ..., "value": ...}shape instead, and a bare scalar value is wrapped into a list. Semantics are additive (upsert by key): the keys you send are added, or their values overwritten if the key already exists — every other existing key is kept, and nothing is ever deleted (an item with no metadata is a no-op). Passmode="append"to add the values you send to the ones a key already holds instead of overwriting them (values it holds already are skipped, so a retry adds nothing twice) — use it for event-log keys such asdeepdots_message, which the default would wipe. Feedbacks not listed are untouched. The feedback ids are checked all or nothing: if any does not exist, is deprecated or belongs to a company you cannot see, the API answers 404 naming them and nothing is written (the SDK raisesrequests.HTTPError); only a failure writing or re-queuing one feedback is listed infailedwhile the rest still land. Each updated feedback re-runs the full analysis pipeline. Returns e.g.{"feedbacks": N, "triggered": M, "failed": [...]}.delete(feedback_id)— soft-deletes the feedback: its status becomesDEPRECATED, it disappears fromget_id, dashboards and reports, and fromgetunless your filter'swheresetsstatus; the SDK has no way to restore it. Returns{}. A latercreate()with the sameexternal_idmakes a new feedback.upload_attachment(feedback_id, file_path, filename=None, extra_data=None, max_attachments=3, check_duplicate_content=True)— uploads a file and attaches it to a feedback. Before uploading it fetches the feedback's existing attachments and enforces two guards (nothing is uploaded if either trips): a maximum ofmax_attachmentsfiles (default 3) per feedback, and no duplicate content — the new file's bytes are SHA-256 hashed and compared against each existing attachment by content, not filename, so re-attaching the same file under a different name raisesValueError. The duplicate check downloads each existing attachment to hash it (best-effort — attachments it cannot download, e.g. a private bucket returning 403, are skipped); passcheck_duplicate_content=Falseto disable it. The cap fails closed: if the feedback's current attachments can't be fetched, the upload is refused rather than risk exceeding the limit.
create, update, get and get_id all normalize the answers,
metadata, metrics and profile fields: each entry is {"key": ..., "value": ...}, and the raw API is inconsistent about value's shape — the
same feedback can have one entry with a bare scalar ("value": "voice") next
to another with a list ("value": ["sln"]). The SDK wraps every bare scalar
as [value], both on what it sends (create/update) and on what it returns
(get/get_id), so callers only ever see/send the list form. questions is a
different shape (title/ref/position/...) and is left untouched; data
is not currently normalized. (profile can only be sent with create():
update() rejects it with 422.)
Feedback source-system fields
When feedback comes from another system (a helpdesk, a review site, a CSV
export...), send these optional fields with create(). They go at the top
level, next to integrationId, not inside answers or
metadata:
| Field | Meaning |
|---|---|
external_id |
ID of the record in the source system, as a string ("48213", not 48213). Makes create() safe to retry: re-sending an id that already exists for the same company, product and integration returns the existing feedback unchanged and never updates it. Send retries for the same id one after another, not in parallel: two simultaneous requests can both create a feedback. Without it nothing is deduplicated, and a retry creates a second copy. |
externalGeneratedAt |
When the feedback happened in the source system. This is the date dashboards, reports and date filters use. If it is omitted, the API stores the time it received the request, so a historical import lands entirely on the import day. |
externalUpdatedAt |
When the record last changed in the source system (defaults to the request time). |
externalUrl |
Link to the original record, shown as the feedback's Original source link. |
The casing is mixed: external_id is the only snake_case field, and every
other field is camelCase (companyId, not company_id).
Send both dates as UTC ISO 8601 strings ending in Z, e.g.
"2026-10-06T11:00:00.000Z" (JavaScript's toISOString() format). The API
stores any string without checking it, but analytics can only read
YYYY-MM-DDTHH:MM:SS[.ffffff]Z, or YYYY-MM-DDTHH:MM:SS with no fraction and
no zone (charts read it as UTC, but the dashboard's feedback list shows it
unconverted, as if it were the viewer's local time, so add the Z). Any other
value is still stored, but analytics can't use it, and in externalGeneratedAt
it makes the feedback drop out of date-filtered charts and reports. That
includes an offset such as +02:00 (Python's default isoformat() of an aware
datetime), fractional seconds without the Z (isoformat() of a naive
datetime that has microseconds, such as datetime.utcnow()), more than six
fractional digits, a date without a time, and a space instead of T. The API stores the value as text, so filters and
sorting compare it as a string. A datetime object raises TypeError in the
SDK, and None or a number gets a 422.
from datetime import datetime, timezone
from zoneinfo import ZoneInfo # Python 3.9+; on Windows also: pip install tzdata
def to_api_datetime(dt):
"""Timezone-aware datetime -> '2026-10-06T11:00:00.000Z'."""
if dt.utcoffset() is None:
raise ValueError("Naive datetime: attach the source time zone first, e.g. dt.replace(tzinfo=ZoneInfo('Europe/Copenhagen'))")
return dt.astimezone(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
The helper refuses naive datetimes because astimezone() would treat them as
machine-local time: attach the source zone first
(dt.replace(tzinfo=ZoneInfo("Europe/Copenhagen"))).
Re-sending a feedback does not fix its date (see external_id). Instead,
PATCH the date and re-run the analysis in the same call:
client.feedbacks.update(feedback_id, {
"externalGeneratedAt": "2026-10-06T11:00:00.000Z",
"status": "REGISTERED",
})
Like every update() that sends "status": "REGISTERED", that is a full re-analysis:
- The summary, issues and topics are regenerated, and issue triage starts over.
- Automations on feedback completion fire again.
- Once the new analysis finishes
DONE, charts and reports can take up to an hour to settle. Check withget_id()thatstatusis back toDONE: if the run endsPARTIALorERROR, charts keep showing the old date until a later analysis finishesDONE: send the same update again.
Send "status": "REGISTERED" only once the feedback has finished processing;
while it is still REGISTERED or PROCESSING it starts a second analysis.
If some feedbacks stay REGISTERED or PROCESSING long after the rest have
finished, they are probably not being analysed at all (for example because an
answer value is a number, or their identity is not analysed); ask your
Deepdots contact instead of re-sending them.
Patching the date without "status": "REGISTERED" updates the stored feedback
only, and charts and reports keep the old date until it is next re-analysed.
Any update() of a feedback whose status is DONE, even without status,
fires the feedback-completion automations again. The API user needs a role
with feedback-update permission (otherwise 405). Don't send an empty
externalGeneratedAt to update(): unlike create(), update() stores it as
it is, and the feedback then drops out of date-filtered charts and reports. If
you need to re-analyse many feedbacks, talk to your Deepdots contact before you
start.
client.contacts
-
create(contact),get(filter=None),update(contact_id, contact),delete(contact_id). Whencreate()sends anexternalIdthe company already has, whatever that contact's status, no contact is added: the API returns that contact updated with the fields you sent (emailincluded,customFieldsmerged) and brings it back to ACTIVE if it was deleted; an unsubscribed contact stays unsubscribed, and if your role can't update contacts it comes back unchanged. Without anexternalId,create()always adds a contact, even for an email the company already has. This is a check before inserting, not a unique constraint: a company can still have several contacts with the sameexternalId. -
upsert(contact)— create-or-update a single contact viaPOST /crm/contacts/upsert. Prefer this overcreate()when the record may already exist. It updates the company's ACTIVE contact with the same email; if there is none, the contact holding theexternalIdyou send, which then takes your email and comes back to ACTIVE if it was deleted; otherwise it creates one. Only ACTIVE contacts are matched by email: an unsubscribed or deleted contact is found only through theexternalIdyou send, and without itupsert()creates a new ACTIVE contact with the same email. On the update branch scalars are overwritten andcustomFieldsis merged (same additive semantics asupdate_fields); the key the contact was matched by (its email, or itsexternalId) is never rewritten.name,email,companyIdare required. Returns the contact after the upsert.client.contacts.upsert({ "name": "Ada", "email": "ada@example.com", "companyId": "ACME", "customFields": {"loyalty_tier": "gold"}, })
-
upsert_batch(items, chunk_size=500)— upsert many contacts viaPOST /crm/contacts/upsert/batch, automatically chunkingitemsto the server cap (500) so you can pass a list of any length. Sending a batch is the pool-friendly way to do bulk (one sequential request per chunk instead of N parallel calls racing the DB connection pool). Best-effort per item: an item that fails on its own (bad email, inaccessible company, ...) is collected infailedand the rest still land. Returns aggregated{"contacts", "created", "updated", "failed"}; eachfailedentry'sindexpoints into the originalitemslist.result = client.contacts.upsert_batch([ {"name": "Ada", "email": "ada@example.com", "companyId": "ACME", "customFields": {"tier": "gold"}}, {"name": "Alan", "email": "alan@example.com", "companyId": "ACME"}, # ... pass thousands; the SDK splits them into 500-item requests ]) print(result["created"], result["updated"], result["failed"])
-
update_fields(contact_id, custom_fields=None, **native_fields)— additively merge custom fields into a contact viaPATCH /crm/contacts/{id}/fields. The refs you send are upserted, every other custom field is kept, and a value ofNoneremoves its ref. Prefer this overupdate()for custom fields:update()writes thecustomFieldsobject whole, so setting one field there deletes all the others.custom_fieldsvalues may bestr/int/float/bool. You may also pass native columns as keywords —name,lastname,phone,address,city,state,postalCode— anything else (email,externalId,status,country,type) is rejected with a 400; useupdate()for those. Returns{"id": ..., "customFields": {...}}, the full field set after the merge.# Add / overwrite custom fields, keeping any others the contact already has client.contacts.update_fields(contact_id, {"loyalty_tier": "gold", "vip": True}) # Remove a custom field client.contacts.update_fields(contact_id, {"loyalty_tier": None}) # Custom fields + a native column in one call client.contacts.update_fields(contact_id, {"nps_segment": "promoter"}, city="Copenhagen")
client.crm
CRM objects are the records a company keeps next to its contacts (tickets,
matches, memberships, ...). Each is stored as (companyId, type, externalId)
plus a free-form data object, and survey answers can be linked to them
through the survey link's URL parameters.
upsert_objects sends 500 records per request (pass a list of any length, or
one record as a dict) and returns totals over all requests, with each failed
entry's index pointing into the list you passed. Failures are per record: a
record the API cannot store is listed in failed and the others still land. A
request must stay under the API's 1 MB body limit: at the default 500 records
per request that is about 2 KB of JSON per record on average. For larger
records pass a smaller chunk_size.
Every request, reads included, is resent up to 3 times (after 2s, 4s, 8s) when
it fails temporarily (502/503/504, a connection error, or no answer within 300
s), and if the token has expired the client logs in again once and resends. If
a request still fails after that, the call raises a
requests.RequestException (HTTPError for an error answer, ConnectionError
or Timeout for the network); the requests before it have already been
applied.
Resending records never creates duplicates: they are matched by their
externalId. Items with sourceUpdatedAt keep the newest version, while items
without it store the last one sent. So after a failure, resend the same list
right away, but never resend an older export after newer changes have been
sent.
upsert_objects(object_type, items, company_id=None, chunk_size=500)— create-or-update objects of one type viaPOST /crm/objects/{type}/upsert/batch, matched byexternalId(required). Other item fields:status,contactKey,parentType,parentKey,startsAt,endsAt,sourceUpdatedAt,data. A field left out keeps what is stored, anddatais merged key by key. Returns{"count", "created", "updated", "failed"}.get_objects(object_type, company_id=None, external_id=None, status=None, parent_type=None, parent_key=None, contact_key=None, limit=None, after=None)— list objects of one type, ordered byexternalId, viaGET /crm/objects/{type}. Filters match exactly. Pages holdlimitobjects (default 100, max 1000); for the next page pass the lastexternalIdasafter.
company_id is required for admin accounts (the API answers 400 without it).
Other users read and write their own company by default; they can also name
another company they belong to, and any other company is refused with 403.
from deepdots_sdk import Deepdots
client = Deepdots("api-user@example.com", "password",
auth_source="identity", base_url="https://api.deepdots.com")
result = client.crm.upsert_objects("match", [
{"externalId": "1001", "startsAt": "2026-11-15T16:00:00Z",
"data": {"name": "Northside - Riverside"}},
])
print(result["created"], result["updated"], result["failed"])
tickets = client.crm.get_objects("ticket", contact_key="C-1001")
client.campaigns
create(campaign),get(filter=None)create_session(campaign_id, session),get_sessions(campaign_id, filter=None),get_sessions_feedbacks(campaign_id, filter=None)
client.metrics
get(filter=None)kpi_ranking(company_id, dimension, formulas, start_date=None, end_date=None, integrations=None, products=None, min_responses=None, limit=None, filters=None, breakdown=None, compare_start_date=None, compare_end_date=None)(since 1.0.26) — the KPIs the dashboards show, per value of a metric: one item per value ofdimension(an agent, a team, a store...) with each KPI informulasand the KPI of all of them together. See KPIs per agent, team or store.
KPIs per agent, team or store
kpi_ranking() reads the same figures as the dashboard ranking, KPI and KPI-by-group widgets (GET /metrics/insights/kpi-ranking), so a report you build from it matches what your team sees on screen.
agents = client.metrics.kpi_ranking(
"YOUR_COMPANY_ID",
dimension="agent", # the metric whose values you compare
formulas=["csat", "nps"], # the KPI metrics, by name
start_date="2026-11-17", # first and last day, both included
end_date="2026-11-17",
)
for agent in agents:
csat, nps = agent["kpis"] # one per formula, in your order
print(agent["value"], agent["total"], csat["kpi"], nps["kpi"])
overall = agents[0]["kpis"][0]["team_kpi"] if agents else None # every agent together
- Names.
dimensionandformulasare metric names.client.metrics.get({"where": {"companyId": "YOUR_COMPANY_ID"}})lists your metrics; use each one'smetricName. The KPIs are the metrics withtypeFORMULA. - Dates.
start_dateandend_dateare days ("YYYY-MM-DD"or adate), both included, in UTC, of the date the feedback happened (externalGeneratedAt). Leave them out for all dates. - Each item has
value(the agent, team... in lower case, as it is stored),total(its responses with any of the KPIs, each counted once) andkpis, with one entry per formula:kpi(Nonewithout responses),total(responses in that KPI),promotersanddetractors(its positive and negative responses),team_kpiandteam_total(the KPI and the responses of all values together, each feedback counted once),delta(kpi - team_kpi),impact(delta * total / team_total) andhigher_is_better. - Order. Best first, by the first KPI in
formulasthat has responses.min_responsesleaves out the values with fewer responses in that KPI (they still count in the team), andlimitkeeps the first N. - Narrowing.
integrationsandproductstake lists of IDs.filterskeeps only the feedback with given metric values, e.g.[{"name": "team", "values": ["north", "south"]}]: a feedback must match every block and, in a block, any of its values; upper and lower case are the same. - Per integration.
breakdown="integration"adds abreakdownlist to each item: itstotalandkpisin each integration, compared with the team of that integration. - Against another period.
compare_start_dateandcompare_end_date(both or neither) addprev_kpi,prev_totalandchange(kpi - prev_kpi) to each KPI.
The figures change when the dashboards' data is refreshed, so calling more often than that returns the same numbers. Parameters are URL-encoded, so names with spaces, accents or & are safe. Missing company_id, dimension or formulas, or only one comparison date, raises ValueError before any request; a company that is not yours is a 403 (requests.HTTPError).
client.dashboards
get_data(dashboard_id, start_date=None, end_date=None)(since 1.0.26) — a dashboard with what each of its widgets shows, as one dict (GET /dashboard/{id}/data): the same figures your team sees on screen, for the period and filters the dashboard opens on.
doc = client.dashboards.get_data("YOUR_DASHBOARD_ID") # the dashboard= value in its address
print(doc["period"]) # {"name": "Today", "startDate": ..., "endDate": ...}
for widget in doc["widgets"]: # top to bottom
print(widget["title"], widget["type"], widget["data"])
# Another period instead of the dashboard's own (days, both included, UTC):
october = client.dashboards.get_data("YOUR_DASHBOARD_ID", start_date="2026-10-01", end_date="2026-10-31")
Each widget has id, title, type, layout, config and data, which is None for a widget whose data is not available this way. The KPI widgets give:
prefab.counter-kpi:formula,label,unit,dimension,kpiandtotal(its responses).prefab.kpi-ranking:dimension,kpis,reference(every value together: itskpiandtotalper formula) androws, every value withrank,value,total,shown(whether the dashboard displays it, e.g. the top 3) and itskpis(kpi,deltaagainst the reference,total,promoters,detractors).prefab.kpi-graph:formula,label,unit,dimension,averageandrows(value,kpi,total), in the chart's order.
Values such as agent names are in lower case, as they are stored. Your user's metric restrictions apply, as in Deepdots. A dashboard that doesn't exist or that you can't see is a 404, another company's a 403 (requests.HTTPError).
client.products
get(filter=None)
client.companies
get(filter=None),get_id(id, filter=None)
client.integrations_questions
get(integration_id, filter=None)
client.reports
get(filter=None),get_newsletter(filter=None),update(report_id, report)
client.requests
get(filter=None),get_id(request_id, filter=None),update(request_id, request)
To mark a request DONE/ERROR asynchronously, publish a completion event to the
request-done Pub/Sub topic (project magicfeedback-prod-api, topic
request-done); the request-done Cloud Function consumes it and PATCHes the
request. The SDK does not publish this itself — build the envelope with
build_done_message and publish it directly. See
examples/mark_request_done.py.
Examples
# Create a feedback
client.feedbacks.create({
"name": "Test Feedback",
"type": "APP",
"identity": "MAGICFORM",
"integrationId": "your-integration-id", # companyId and productId are taken from it
"answers": [
{"key": "score", "value": "4"},
{"key": "comment", "value": "Great service!"},
],
# Optional source-system fields: top level, see "Feedback source-system fields"
"external_id": "48213",
"externalGeneratedAt": "2026-10-06T11:00:00.000Z",
"externalUrl": "https://forms.example.com/responses/48213",
})
# Get a feedback with its attachments
client.feedbacks.get_id(
"<feedback_id>",
filter={"include": [{"relation": "feedbackAttachments"}]}
)
# Upload a file attachment.
# A feedback holds at most 3 attachments, and a file whose bytes are identical
# to one already attached (even under a different name) is rejected with a
# ValueError — nothing is uploaded in either case.
client.feedbacks.upload_attachment(
"<feedback_id>",
file_path="/path/to/file.pdf",
filename="report.pdf", # optional, defaults to file name
extra_data={"source": "crm"}, # optional, any JSON-serialisable dict
# max_attachments=3, # optional, override the per-feedback cap
# check_duplicate_content=False, # optional, skip the byte-for-byte dedupe
)
# Mark a request DONE via the request-done Pub/Sub topic.
# The SDK builds the envelope; the producer publishes it directly.
import json
from google.cloud import pubsub_v1
from magicfeedback_sdk.api.requests import build_done_message
message = build_done_message(
"<request_id>",
"<company_id>",
output={"value": "…final result…"},
sources=["<feedbackId1>", "<feedbackId2>"], # optional
logs="processed 2 items", # optional
# success=False, error={"message": "processing failed"} # to mark ERROR
)
publisher = pubsub_v1.PublisherClient()
topic_path = publisher.topic_path("magicfeedback-prod-api", "request-done")
publisher.publish(topic_path, json.dumps(message).encode("utf-8")).result()
Logging
import logging
client.set_logging(logging.DEBUG)
License
MIT
Contributing
Developing on the SDK itself — layout, tests, and how to cut a release — is documented in DEVELOPERS.md.
Contact
Metadata
Release files for magicfeedback 1.0.26
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| magicfeedback-1.0.26.tar.gz | 61.1 kB | Without provenance | Details for magicfeedback-1.0.26.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| magicfeedback-1.0.26-py3-none-any.whl | Python 3 | none | any | Details for magicfeedback-1.0.26-py3-none-any.whl |
Total release size: 108.7 kB
Release files / magicfeedback-1.0.26.tar.gz
| Download URL | magicfeedback-1.0.26.tar.gz |
|---|---|
| Size | 61.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
29103dca676dbef8108ab8abfdd90ccf6e174fe23184ca0b4e5b9241e88e17d7
|
|
BLAKE2b-256 checksum How to use checksums |
7050c05c2f6e8491db4660d565374c10943e17f0083ee23c212cdeabc8ceb11d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Release files / magicfeedback-1.0.26-py3-none-any.whl
| Download URL | magicfeedback-1.0.26-py3-none-any.whl |
|---|---|
| Size | 47.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c23b02b760e49856a929735164f3d2132857888e82eb57e2b4003b5d464462a1
|
|
BLAKE2b-256 checksum How to use checksums |
2529de1d9970df7a25d03008ecabbfbf64570c8e39a80fcccb23f7e5c6703025
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Security for magicfeedback 1.0.26
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.